9 ms·

In practice there are 3 types of comments: - documentation, that should be parsed by some external tool (javadoc, godoc, etc.) - warnings in the code, like th

In practice there are 3 types of comments: - documentation, that should be parsed by some external tool (javadoc, godoc, etc.) - warnings in the code, like the "this call is very important because of..." example from the article - commented out code. I want warnings to sitck out, but I don't want doc to stick out. Commented-out code should not exist, granted, but in the meantime I don't want it to stick out either. If I'm commenting-out my own code, that's because I'm trying to understand some issue, so please don't distract me. I'll remove it later, I promise.

taneq 7y ago
> If I'm commenting-out my own code, that's because I'm trying to understand some issue, so please don't distract me. I'll remove it later, I promise. This is where multiple rulesets could come in handy. Your editor which you're using for debugging should keep the commented-out code nice and subtle, but when you go to commit it should be bright purple with yellow spots.
- jakear 7y ago
  You could actually do exactly that in VSCode. I might have to try making it.
flohofwoe 7y ago
Why "require" documentation comment blocks to be parsed by external tools and read elsewhere? It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. The current "fashion" of making comments as unreadable as possible in most syntax highlighter themes is indeed my main gripe with them. Comments don't have to particularly stick out, but it would at least help to make them as readable as the actual source code.
- rightbyte 7y ago
  Ye. Reading eg. Javadoc verbatim is awefull. There are nice doc generators that allow natural language with markup only for special attributes.
- lifthrasiir 7y ago
  > It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. If you need to read the source code to use a library, something is wrong with that library. (On the other hands it is fine to document local functions, but it doesn't need to be a verbose documentation comment.)
  - jgtrosh 7y ago
    Quite the opposite, a library can be understood fast and in depth when the code and its comments are readable directly, skipping the indirection layer of any external documentation.
    - lifthrasiir 7y ago
      "in depth" is probably correct, but "fast" depends. I tend to classify libraries into two classes, something I can obviously make but I don't have to, and something I would have to try hard (or even be impossible) to make it. You can't quickly understand the second class of libraries by reading the code. If you need a concrete example, take miniSAT [1] as one. [1] https://github.com/niklasso/minisat/blob/master/minisat/core/Solver.cc https://github.com/niklasso/minisat/blob/master/minisat/core...
  - flohofwoe 7y ago
    I'm thinking of examples like this: https://github.com/nothings/stb/blob/master/stb_image.h https://github.com/nothings/stb/blob/master/stb_image.h It's a complete image loader library in a single header. This header contains everything I need to use that library: the entire documentation, the license, public API declarations and finally the implementation source code. I can read this file from top to bottom to know every little detail about this library, or I can stop somewhere inbetween (for instance when I only want to know how to use the library and what the API looks like, but I'm not interested in the implementation details).
    - lifthrasiir 7y ago
      First, I consider a single header library as a symptom from the lack of fine package managers for C and not as a feature. Such a form should not have been a norm at all. Also note that stb_image is extremely stateless. The documentation is not a must for stateless APIs because it is relatively easier to infer from the signature (of course you need to learn the convention, for example, to see that `int x, int y` etc. are out parameters and should not be NULL though). But many other libraries need states, and a proper documentation is required.
mcv 7y ago
So a good syntax highlighter should differentiate between these different kinds of comments. Grey out the javadoc stuff, but emphasize the informative and warning comments. And I think it could be really useful and commented-out code would still be highlighted, but in a washed out way or some other way that emphasises it's not currently active code.
- hibbelig 7y ago
  > So a good syntax highlighter should differentiate between these different kinds of comments. Grey out the javadoc stuff, but emphasize the informative and warning comments. But those who write Javadoc well, will put important stuff in there. And those who write non-Javadoc comments badly, will put useless stuff there. Looks like an AI-complete problem to distinguish important from unimportant comments...
lightgreen 7y ago
There’s fourth the most important and imho the only important type of comment: a comment which helps understanding why code does what it does when it is not expressed in code itself. E. g. // do two iterations of bubble sort before // falling back two qsort // because 99% of data comes almost sorted This information cannot be obtained by reading function body, thus it should be added to comment.
gitgud 7y ago
> Commented-out code should not exist, granted .... I'll remove it later, I promise. In my opinion, you should never commit commented out code. Here's why: 1. Commented out code, just confuses and clutters people's interpretation of the project. It's meaning is not clear as it's not a functioning part of the system. 3. It can incorrectly inflate the apparent complexity of a project. 2. It reduces the impact of meaningful comments, so people end up ignoring all comments. Commit a working-state of the system only. If you're working through a problem, save the functions without commenting them out and completely remove them when you don't need them... you can always go back and find it in the source-control later when you need it. Also, one of the first things I do when coming onto a new project is (switch to a new branch) and remove all the dead code.
- hibbelig 7y ago
  >> Commented-out code should not exist, granted .... I'll remove it later, I promise. > In my opinion, you should never commit commented out code. But the editor works on uncommitted code, too. GP doesn't want to be distracted by that.
  - gitgud 7y ago
    > ... so please don't distract me. I'll remove it later, I promise. It could mean people are literally looking over his shoulder at his screen and complaining. But to me, it implies that commented code is becoming part of the project source...
    - gugagore 7y ago
      Thanks to distributed version control, you can commit all sorts of trash in your own branch while figuring things out. These commits should not clutter the project source, though if you like hoarding data like I do, you might still preserve this history somewhere else in the repository.
    - sacado2 7y ago
      No, I'm talking about my own "private" code in my own editor. This is a conversation with my editor while I'm "in the zone". I (usually) don't commit commented-out code, for the reasons you mentioned above.

taneq 7y ago

> If I'm commenting-out my own code, that's because I'm trying to understand some issue, so please don't distract me. I'll remove it later, I promise. This is where multiple rulesets could come in handy. Your editor which you're using for debugging should keep the commented-out code nice and subtle, but when you go to commit it should be bright purple with yellow spots.

jakear 7y ago
You could actually do exactly that in VSCode. I might have to try making it.

flohofwoe 7y ago

Why "require" documentation comment blocks to be parsed by external tools and read elsewhere? It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. The current "fashion" of making comments as unreadable as possible in most syntax highlighter themes is indeed my main gripe with them. Comments don't have to particularly stick out, but it would at least help to make them as readable as the actual source code.

rightbyte 7y ago
Ye. Reading eg. Javadoc verbatim is awefull. There are nice doc generators that allow natural language with markup only for special attributes.
lifthrasiir 7y ago
> It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. If you need to read the source code to use a library, something is wrong with that library. (On the other hands it is fine to document local functions, but it doesn't need to be a verbose documentation comment.)
- jgtrosh 7y ago
  Quite the opposite, a library can be understood fast and in depth when the code and its comments are readable directly, skipping the indirection layer of any external documentation.
  - lifthrasiir 7y ago
    "in depth" is probably correct, but "fast" depends. I tend to classify libraries into two classes, something I can obviously make but I don't have to, and something I would have to try hard (or even be impossible) to make it. You can't quickly understand the second class of libraries by reading the code. If you need a concrete example, take miniSAT [1] as one. [1] https://github.com/niklasso/minisat/blob/master/minisat/core/Solver.cc https://github.com/niklasso/minisat/blob/master/minisat/core...
- flohofwoe 7y ago
  I'm thinking of examples like this: https://github.com/nothings/stb/blob/master/stb_image.h https://github.com/nothings/stb/blob/master/stb_image.h It's a complete image loader library in a single header. This header contains everything I need to use that library: the entire documentation, the license, public API declarations and finally the implementation source code. I can read this file from top to bottom to know every little detail about this library, or I can stop somewhere inbetween (for instance when I only want to know how to use the library and what the API looks like, but I'm not interested in the implementation details).
  - lifthrasiir 7y ago
    First, I consider a single header library as a symptom from the lack of fine package managers for C and not as a feature. Such a form should not have been a norm at all. Also note that stb_image is extremely stateless. The documentation is not a must for stateless APIs because it is relatively easier to infer from the signature (of course you need to learn the convention, for example, to see that `int x, int y` etc. are out parameters and should not be NULL though). But many other libraries need states, and a proper documentation is required.

mcv 7y ago

So a good syntax highlighter should differentiate between these different kinds of comments. Grey out the javadoc stuff, but emphasize the informative and warning comments. And I think it could be really useful and commented-out code would still be highlighted, but in a washed out way or some other way that emphasises it's not currently active code.

hibbelig 7y ago
> So a good syntax highlighter should differentiate between these different kinds of comments. Grey out the javadoc stuff, but emphasize the informative and warning comments. But those who write Javadoc well, will put important stuff in there. And those who write non-Javadoc comments badly, will put useless stuff there. Looks like an AI-complete problem to distinguish important from unimportant comments...

lightgreen 7y ago

There’s fourth the most important and imho the only important type of comment: a comment which helps understanding why code does what it does when it is not expressed in code itself. E. g. // do two iterations of bubble sort before // falling back two qsort // because 99% of data comes almost sorted This information cannot be obtained by reading function body, thus it should be added to comment.

gitgud 7y ago

> Commented-out code should not exist, granted .... I'll remove it later, I promise. In my opinion, you should never commit commented out code. Here's why: 1. Commented out code, just confuses and clutters people's interpretation of the project. It's meaning is not clear as it's not a functioning part of the system. 3. It can incorrectly inflate the apparent complexity of a project. 2. It reduces the impact of meaningful comments, so people end up ignoring all comments. Commit a working-state of the system only. If you're working through a problem, save the functions without commenting them out and completely remove them when you don't need them... you can always go back and find it in the source-control later when you need it. Also, one of the first things I do when coming onto a new project is (switch to a new branch) and remove all the dead code.

hibbelig 7y ago
>> Commented-out code should not exist, granted .... I'll remove it later, I promise. > In my opinion, you should never commit commented out code. But the editor works on uncommitted code, too. GP doesn't want to be distracted by that.
- gitgud 7y ago
  > ... so please don't distract me. I'll remove it later, I promise. It could mean people are literally looking over his shoulder at his screen and complaining. But to me, it implies that commented code is becoming part of the project source...
  - gugagore 7y ago
    Thanks to distributed version control, you can commit all sorts of trash in your own branch while figuring things out. These commits should not clutter the project source, though if you like hoarding data like I do, you might still preserve this history somewhere else in the repository.
  - sacado2 7y ago
    No, I'm talking about my own "private" code in my own editor. This is a conversation with my editor while I'm "in the zone". I (usually) don't commit commented-out code, for the reasons you mentioned above.