3 ms·

> I do not mind there being long comments in the code. Me neither. If the code is good, its author may put in some Haikus about his thoughts about the meaning

> I do not mind there being long comments in the code. Me neither. If the code is good, its author may put in some Haikus about his thoughts about the meaning of life for all I care. If it's to much, I can use my IDE and just hide it. What bothers me isn't lots of comments per-se, but when more emphasis is put on having lots of comments, than on having good, readable code.

denton-scratch 5y ago
Please, keep the haikus somewhere else. Comments tend not to be maintained with the code. Block-comments up-source often describe general philosophy covering functions way down-source, that may or may not be relevant; does this one-line change on line 200 impact the philosophy comment on line 20? Who cares. Fix the bug, and let's go home. So comments are needed only if the code is tricksy. Tricksy code is to be avoided; code should generally be clear. If it has to be tricksy, then a comment is justified to explain why it isn't clear (otherwise someone will come along and de-tricksify it in the interests of clarity). Code is written for people, not for computers. Otherwise we'd be writing programs in hex (which is how I had to write my first-ever program).
- usrbinbash 5y ago
  > So comments are needed only if the code is tricksy If the code in question is part of the pkg/module/crate/whatever's API, aka. someone else may have to use it some day, it should be commented regardless of how complex it is. Whatever interacts with "the outside world" should be labeled, that's true in code, and that's true with the big red emergency stop button found on heavy machinery. It doesn't matter how obvious the usage is.
  - wott 5y ago
    > If the code in question is part of the pkg/module/crate/whatever's API, aka. someone else may have to use it some day, it should be commented regardless of how complex it is. No, the API should be documented, which is orthogonal to the presence or absence of comments inside the code.
    - denton-scratch 5y ago
      Agree. I suspect the difference of opinion might be down to systems like Javadoc, that transform code comments into API docs. But Javadoc comments are often auto-generated from function prototypes, which results in Javadoc comments that add nothing to the raw code except bloat. I don't think I'ver ever seen good documentation produced from doc-comments. There's another thread on the front page about literate programming; I suspect that doc-comments amount to an effort to weave code and documentation together, in a knuthian manner, to kind-of automate literate programming. It doesn't work, AFAICS. You get bloated code and bad docs.
      - marcos100 5y ago
        Love your comment. doc-comments are good because it explains well what the class/method/whatever are there for, sometimes with examples, that helps understand the code. But I hate that they use so much space inside the source code that I have to scroll hundreds of lines to read the code. And those doc-comments are filled with markup that makes it harder to read. I would like a literate a system that generates source code that is well formatted and where the only comments are what the function does and some inner function comment where the code is complex. Every other lengthy and detailed description should be inside the produced pdf/html.
    - usrbinbash 5y ago
      That depends entirely on the toolset available. Languages like Java, Python or Golang enable inline documentation which can then be used by standardized tools (Javadoc, Docstrings, Godoc). eg. https://pkg.go.dev/flag@go1.17.6#PrintDefaults https://pkg.go.dev/flag@go1.17.6#PrintDefaults The entire documentation of this function (including HTML) is generated by the Godoc tool reading comments which conform to a certain convention. https://cs.opensource.google/go/go/+/refs/tags/go1.17.6:src/flag/flag.go;l=541 https://cs.opensource.google/go/go/+/refs/tags/go1.17.6:src/... There is literally no downside to this. The code and its documentation are in the same file, its much simpler for developers to update it when there is a change, and its easy to generate documentation directly from source on the fly.

denton-scratch 5y ago

Please, keep the haikus somewhere else. Comments tend not to be maintained with the code. Block-comments up-source often describe general philosophy covering functions way down-source, that may or may not be relevant; does this one-line change on line 200 impact the philosophy comment on line 20? Who cares. Fix the bug, and let's go home. So comments are needed only if the code is tricksy. Tricksy code is to be avoided; code should generally be clear. If it has to be tricksy, then a comment is justified to explain why it isn't clear (otherwise someone will come along and de-tricksify it in the interests of clarity). Code is written for people, not for computers. Otherwise we'd be writing programs in hex (which is how I had to write my first-ever program).

usrbinbash 5y ago
> So comments are needed only if the code is tricksy If the code in question is part of the pkg/module/crate/whatever's API, aka. someone else may have to use it some day, it should be commented regardless of how complex it is. Whatever interacts with "the outside world" should be labeled, that's true in code, and that's true with the big red emergency stop button found on heavy machinery. It doesn't matter how obvious the usage is.
- wott 5y ago
  > If the code in question is part of the pkg/module/crate/whatever's API, aka. someone else may have to use it some day, it should be commented regardless of how complex it is. No, the API should be documented, which is orthogonal to the presence or absence of comments inside the code.
  - denton-scratch 5y ago
    Agree. I suspect the difference of opinion might be down to systems like Javadoc, that transform code comments into API docs. But Javadoc comments are often auto-generated from function prototypes, which results in Javadoc comments that add nothing to the raw code except bloat. I don't think I'ver ever seen good documentation produced from doc-comments. There's another thread on the front page about literate programming; I suspect that doc-comments amount to an effort to weave code and documentation together, in a knuthian manner, to kind-of automate literate programming. It doesn't work, AFAICS. You get bloated code and bad docs.
    - marcos100 5y ago
      Love your comment. doc-comments are good because it explains well what the class/method/whatever are there for, sometimes with examples, that helps understand the code. But I hate that they use so much space inside the source code that I have to scroll hundreds of lines to read the code. And those doc-comments are filled with markup that makes it harder to read. I would like a literate a system that generates source code that is well formatted and where the only comments are what the function does and some inner function comment where the code is complex. Every other lengthy and detailed description should be inside the produced pdf/html.
  - usrbinbash 5y ago
    That depends entirely on the toolset available. Languages like Java, Python or Golang enable inline documentation which can then be used by standardized tools (Javadoc, Docstrings, Godoc). eg. https://pkg.go.dev/flag@go1.17.6#PrintDefaults https://pkg.go.dev/flag@go1.17.6#PrintDefaults The entire documentation of this function (including HTML) is generated by the Godoc tool reading comments which conform to a certain convention. https://cs.opensource.google/go/go/+/refs/tags/go1.17.6:src/flag/flag.go;l=541 https://cs.opensource.google/go/go/+/refs/tags/go1.17.6:src/... There is literally no downside to this. The code and its documentation are in the same file, its much simpler for developers to update it when there is a change, and its easy to generate documentation directly from source on the fly.