I don’t think examining the intuitiveness and explicitness of each potential syntax in a vacuum is the right way to frame the discussion. Rather, we should look at the menu of possible syntaxes that people elsewhere use to serve this purpose, and pick or adapt the one we like the best. In particular, we should explicitly avoid being too novel: the innovation here is in the scala-cli runtime and the way it provides a batteries-included way to get started with Scala. We shouldn’t be in the business of making innovative new metadata formats.
Examples of other languages doing similar things include:
Kotlin file annotations
@file:Repository("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven")
@file:DependsOn("org.jetbrains.kotlinx:kotlinx-html-jvm:0.7.3")
import kotlinx.html.*
import kotlinx.html.stream.*
import kotlinx.html.attributes.*
Java/Scala Annotations:
@AnnotationName()
@AnnotationName(value = "elementValue")
@AnnotationName("elementValue")
Javadoc:
/**
* @author Firstname Lastname <address @ example.com>
* @version 1.6 (current version number of program)
* @since 1.2 (the version of the package this class was first added to)
*/
Markdown/HTML front matter
---
title: YAML Front Matter
description: A very simple way to add structured data to a page.
---
<h1> {{ title }} </h1>
<p> {{ description }} </p>
Page content here...
Go compiler directives:
//go:norace
C++ directives:
#define TABLE_SIZE 100
Python file encodings
# coding: pyxl
Swift Annotations
// MARK: - View Life Cycle
override func viewDidLoad() {
super.viewDidLoad()
// Setup View
setupView()
// FIXME: Fix Bug
}
Overall, there are roughly 3 categories: @-based syntax (Java/Javadoc/Kotlin), YAML-based syntax (Markdown/HTML), and comment-ish-based syntax (Go/C++/Python).
I don’t have a strong opinion on whose lead we should follow, but I do feel strongly that we should follow/adapt some existing convention and not come up with our own thing. The current proposal //> using ... prefix for annotations, while workable, manages to look exactly like no other syntax anywhere else in the programming community, and also looks like no other syntax someone would find in the Scala language (even the re-use of using is questionable: the syntax is different, as is the meaning). That’s an unnecessary stumbling block for onboarding developers, whether they have prior experience in Scala or in other languages.
IMO, adapting any of the existing conventions would be an improvement over the current proposal, if only due to the familiarity it would provide. e.g.:
Kotlin/Java-annotations-style
@file("utils.scala")
@dep("org.scalatest::scalatest:3.2.10")
@jvm("11")
println("Hello World!")
Javadoc-style
// @file utils.scala
// @dep org.scalatest::scalatest:3.2.10
// @jvm 11
println("Hello World!")
Front-matter style
/***
file: utils.scala
dep: org.scalatest::scalatest:3.2.10
jvm: 11
***/
println("Hello World!")
These are all strawman examples I just made up, and may need some tweaking. But IMO they would be much more familiar to the broader programming community, which is a plus if we hope Scala-CLI would help us reach people who are not already deeply embedded in the Scala way of thinking
