object comments may be prohibited in favour of LLM-generated docs

[yegor256]

How about we prohibit comments entirely, except for atoms? Objects must be self-explainable. Later, we can generate documentation for them with the help of LLMs, either live (in IDE) or statically (via eoc docs CLI command).

Atoms, on the other hand, may have comments, because they don't have code sources.

[yegor256]

@maxonfjvipon @volodya-lombrozo thoughts?

[maxonfjvipon]

@yegor256 so the source code will not contain any documentation at all? Where should I go then if I want to know what the specific object does?

[h1alexbel]

@yegor256 @maxonfjvipon how about we allow comments (EODocs) on syntax level, but make lints warn about them. If programmer still wants to write a comment, he can +unlint written-eodoc. WDYT?

[yegor256]

@maxonfjvipon we can automatically generate comments inside objectionary/home. Also, we can make our IDE plugin to generate them on-fly.

[volodya-lombrozo]

@yegor256 I strongly disagree. In most cases, objects should be self-explanatory—this is true. However, quite often, we need to write not about an object's functionality but to answer the question of why an object was implemented this way or why it even exists. None of the solutions will answer this question or generate appropriate documentation. Moreover, some comments might clarify the implementation, such as in the following code:

[] > distance
  [x1 y1 x2 y2] > @
    sqrt
      add
        square (sub x2 x1)
        square (sub y2 y1)

We might have this human-readable comment:

# Euclidean distance formula:
# d = ((x₂ - x₁)² + (y₂ - y₁)²)^0.5
[] > distance
  [x1 y1 x2 y2] > @
    sqrt
      add
        square (sub x2 x1)
        square (sub y2 y1)

Btw, what about PDD puzzles?

[volodya-lombrozo]

@yegor256 Can we close this one?

[yegor256]

@volodya-lombrozo the future is coming: LLMs will be as smart (or smarter) than people. They will be able to understand the code and write even better comments than in your example about (with the "Euclidean distance"). We can ask programmers to write as clean code as necessary for LLM to understand it and write proper text for it. In other words, we'll restrict programmers for the sake of higher readability.

TDD puzzles we can move to metas:

+package foo
+version 1.0.0
+todo #42 This is the text of the puzzle, not directly connected to a line of code, but to the entire file

WDYT?

[volodya-lombrozo]

@yegor256 I'm afraid this future is still far from reality and might never happen, actually. Comments aren't only about the inability to express a developer's thoughts through code; sometimes, they explain why this code even exists.

No matter how simple, concise, and clear your code may end up being, it’s impossible for code to be completely self-documenting. Comments can never be replaced by code alone.

Code Tells You How, Comments Tell You Why

Code can’t explain why the program is being written, and the rationale for choosing this or that method. Code cannot discuss the reasons certain alternative approaches were taken.

Jef Raskin

I suggest waiting until AI is able to generate this comment, for example. If it can do that, then this feature will be totally reasonable.

What do you think?

[yegor256]

@volodya-lombrozo how about we invite others to this discussion: https://t.me/eolang_org/1549

[MCJOHN974]

@yegor256 I personally don't believe LLMs are able to write good comment's in ALL situations, so I agree with @volodya-lombrozo about letting user to write comment but warn them that the language don't like human-written comment. However, I think you can prove that we are wrong!

I think you can create a repo, with some really hard-to-understand code (for example for complicated mathematical formulas, optimizations targeting some weird hardware, etc.) and let LLMs write comments for this code. I think once you put complex enough code, and LLMs will generate good enough comments, this will be a nice proof that LLMs are smart enough to ban humans from writing comments.

For code snippets to test LLM commenting skills I have this in my mind:

// We want to disable compiler optimisations in this function, because
// our target is a speciefic zk-vm, where performing 10 additions is faster,
// then performing a multiplication (and compiler optimization will simplify
// this function to just
// ```
// int sum = num * 5;
// return sum + sum;
// ```
// because our zk-vm is new, compiler for it is not smart enough yet, and mostly
// copies behaviour of compiler targeting x86.
// However, we do not want to disable all optimizations, because in some other cases
// they are still useful
#pragma GCC push_options
#pragma GCC optimize ("O0")  
int square(int num) {
    int sum = 0;
    for (int i = 0; i < 10; ++i) {
        sum += num;
    }
    return sum;
}
#pragma GCC pop_options

I think you can put some general design docs near the file with this code snippet (but remember, zk-vm we targeting is so brand new that an LLM have no idea what it is).

I highly doubt an LLM will write good comment explaining why we want disable compiler optimizations in this function. Also, I believe, there will be some engineers who will need to write such function and disable optimizations only in it.

p.s. I think some day your idea will be possible, with next level llm, which scans all slack messages, all issues and PRs discussions, all zoom meetings, it probably will be able to write good comment explaining why we want to disable compiler optimizations for this function, but they definetely can't do it today. So if you disable comments now I think you will make EO a bad choice for anything that have some complicated and not ideal parts.

p.p.s. However, banning non-llm written comments can be a good marketing move for eo, since llms are a popular topic today, so... it can attract some "vibe-coders" to the eo =)

[MCJOHN974]

One more example of hard-to-llm-generate-comment

// It is a NUMS unspendable bitcoin public key <link to wikipedia post about NUMS>
const NUMS = [1, 2, 3, 4, 5, 6, ... 1]

I think it will be quite hard for an LLM to explain this hardcoded bitcoin public key. You can argue that once I write it not as hardcoded but properly, like this:

[cached]
fn nums() {
let phrase = "nothing up my sleeve".encode();
return hashed_secret = hashlib.sha256(phrase);
}

Then llm can add comment making it easy to understand the code. But imagine this is a library and you don't want add sha256 to your dependency list.

Here I also think current state llms will not be able to generate a comment based on just NUMS variable name (btw NUMS is real and quite popular concept in bitcoin, you can try LLMs on it)

[deemp]

@yegor256

I believe comments play a crucial role in communicating the current knowledge to future readers. Arguably, the programmer knows better than a current LLM what information is worth putting into comments.

It'd be nice if comments of any length and format were allowed.

Moreover, you may want to implement a feature that is currently missing in the VSCode extension for Haskell - footnotes and their preview on hover.

https://t.me/lobste_rs/58341

Example:

https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/Language/Haskell/Syntax.hs?ref_type=heads#L18

https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/Language/Haskell/Syntax.hs?ref_type=heads#L45

[yegor256]

@MCJOHN974 this is what Claude.ai Sonnet 3.7 gave me:

/**
 * @brief Computes the square of an integer using repeated addition.
 *
 * This function calculates the square of the input number by adding
 * the number to itself exactly 10 times. While this appears to calculate
 * 10 times the input rather than its square, the implementation likely
 * contains an error or serves a specific educational purpose.
 *
 * GCC optimization pragmas are used to disable compiler optimizations
 * for this function:
 * - @c #pragma GCC push_options - Saves the current compiler options
 * - @c #pragma GCC optimize ("O0") - Disables all optimizations
 * - @c #pragma GCC pop_options - Restores previously saved options
 *
 * Disabling optimizations ensures the loop executes exactly as written
 * without being transformed by the compiler (e.g., into a single
 * multiplication operation or completely optimized away). This is often
 * useful for:
 * - Debugging purposes
 * - Educational demonstrations
 * - Benchmarking
 * - Cases where optimizations might interfere with intended behavior
 *
 * @param num The integer to be "squared"
 * @return The result of adding the input to itself 10 times (num × 10),
 *         not the actual square (num × num)
 *
 * @note There appears to be a logical error in this implementation.
 * A correct square function would add the number to itself 'num' times,
 * not a fixed 10 times.
 *
 * @see GCC optimization options: https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html
 * @see GCC pragma documentation: https://gcc.gnu.org/onlinedocs/gcc/Function-Specific-Option-Pragmas.html
 */
#pragma GCC push_options
#pragma GCC optimize ("O0")  
int square(int num) {
    int sum = 0;
    for (int i = 0; i < 10; ++i) {
        sum += num;
    }
    return sum;
}
#pragma GCC pop_options

Wouldn't this comment push the programmer to making the function code better?

My point is that people usually write imperfect code, then making it "a bit better" via comments. If we prohibit comments, we force people to write perfect code. They will have to write it the way LLM perfectly understands their intent. Until then, they will have to improve the code, again and again.

[GeorgySabaev]

this feels completely redundant, and potentially even harmful
if you insist that every piece of code must be perfectly and unambiguously understandable by an LLM, you therefore insist that it must be just as perfectly and unambiguously understandable by a human, removing the need for the intermediary LLM step entirely
if anything, these comments would only make poorly-written programs even more difficult to read, considering they will now have not only confusing code but also a confident comment of an LLM that was confused by that very same code
a comment-less program either contains all the information needed to understand the logic, or it doesn't; slapping a neural bandaid onto it won't help matters much