4 ms·

Literate programming is certainly a great idea. The problem starts when it is implemented badly in a project, and instead of code that is easier to read, the de

Literate programming is certainly a great idea. The problem starts when it is implemented badly in a project, and instead of code that is easier to read, the devs are faced with files stuffed with "comment-noise". Should we try to write code that is primarily meant to be read? YES! Oh god yes! Code is read 1000x more than it is written. But that doesn't mean "stuff the code with comments". Primarily, it means write code that is clear, concise, conveys the meaning, is logically structured, is not "optimized" into obscurity before even the first performance measurement has been done, and doesn't implement something just to fulfill some dogmatic paradigm. Once that's in the bank, we can start using comments where they are needed: Explain Functions that are part of the interface, explain functions that have complex logic, explain imports that aren't part of the stdlib or well known 3rd party libraries. I don't need a comment telling me what `import requests´ is needed for. I certainly do need a comment telling me what the hell `from apputil.tools import tvectorization` does.

zelphirkalt 5y ago
Mostly agree, but I want to narrow down a few points: Collectively, we already fail at the first stage, writing code, which is well structured and through its structure conveys meaning and understanding. It is rare, that I see this being done in a way, that makes me think: "Ah, great code!" Perhaps in SICP or in some conference talks I see it more often, when people know, they are going to present it and it should be done really well. When I see some typical algorithm video however, people seem to get a kick out of explaining comparatively unreadable code, instead of first structuring it really well. Structuring code really well is an art and certainly one cannot always do as great as some of the greats, who had years time to improve some snippet. Code being read 1000x more than written might be an exaggeration, or over-generalization, as not all code will be written to last years, however, I agree with the basic idea it implies. I do not mind there being long comments in the code. I have done so myself, as long as they are useful for an in-depth understanding. You might get into a situation, where you work with an API, which when the concept that is implemented behind it would make things clear, but you do not want to assume understanding of those concepts by the reader of your code. Of course you could say, that they must read the docs of those concepts then, but what if that is a paper, which takes days to read and understand yourself? Maybe you can put very helpful explanation in some comments, to safe others lots of time.
- usrbinbash 5y ago
  > 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.
pbowyer 5y ago
This "too many comments" argument comes up every time, and I say it's a straw man argument. Apart from new programmers who put those comments in to remind themselves what each line does, I haven't seen "comment-noise" since... 2005 sounds right. If it was common I'd be able to go on GitHub and have my searches spoiled by comments. But instead on GitHub it's the opposite, as it is in my working life: people have gone to a "we don't write comments" default position. Getting a balance is necessary, but I'd rather we had programmers over-commenting than under-commenting, especially for open source projects where "read the code" is used to mean "we don't need documentation as our code's so great". It also depends who is going to read the code. Other experienced programmers need different comments than when my code is going to be read by developers who are unfamiliar with the codebase and didn't expect to ever touch it. I agree with what you say but I encourage people to add comments and then remove them later if not needed, rather than omit them entirely.
- emodendroket 5y ago
  I don’t. I worked on a program with hundreds of instances of the comment “do this here.” Why not just preface every line with that?
  - Supermancho 5y ago
    > Why not just preface every line with that? Because that's noise that makes reading the code more difficult. Creating a separate markup file that provides comments (even overlapping) that are associated to files and lines, for display in an IDE window seems like the logical way to go from the current style of inlining comments into code.
    - emodendroket 5y ago
      I have my doubts. It seems like that would be even more likely to drift than inline comments.
      - Supermancho 5y ago
amelius 5y ago
We need a programming language that only allows writing at the bottom of the code. That way, the thoughts of the programmer become more linear, and the code becomes easier to read.

zelphirkalt 5y ago

Mostly agree, but I want to narrow down a few points: Collectively, we already fail at the first stage, writing code, which is well structured and through its structure conveys meaning and understanding. It is rare, that I see this being done in a way, that makes me think: "Ah, great code!" Perhaps in SICP or in some conference talks I see it more often, when people know, they are going to present it and it should be done really well. When I see some typical algorithm video however, people seem to get a kick out of explaining comparatively unreadable code, instead of first structuring it really well. Structuring code really well is an art and certainly one cannot always do as great as some of the greats, who had years time to improve some snippet. Code being read 1000x more than written might be an exaggeration, or over-generalization, as not all code will be written to last years, however, I agree with the basic idea it implies. I do not mind there being long comments in the code. I have done so myself, as long as they are useful for an in-depth understanding. You might get into a situation, where you work with an API, which when the concept that is implemented behind it would make things clear, but you do not want to assume understanding of those concepts by the reader of your code. Of course you could say, that they must read the docs of those concepts then, but what if that is a paper, which takes days to read and understand yourself? Maybe you can put very helpful explanation in some comments, to safe others lots of time.

usrbinbash 5y ago
> 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.

pbowyer 5y ago

This "too many comments" argument comes up every time, and I say it's a straw man argument. Apart from new programmers who put those comments in to remind themselves what each line does, I haven't seen "comment-noise" since... 2005 sounds right. If it was common I'd be able to go on GitHub and have my searches spoiled by comments. But instead on GitHub it's the opposite, as it is in my working life: people have gone to a "we don't write comments" default position. Getting a balance is necessary, but I'd rather we had programmers over-commenting than under-commenting, especially for open source projects where "read the code" is used to mean "we don't need documentation as our code's so great". It also depends who is going to read the code. Other experienced programmers need different comments than when my code is going to be read by developers who are unfamiliar with the codebase and didn't expect to ever touch it. I agree with what you say but I encourage people to add comments and then remove them later if not needed, rather than omit them entirely.

emodendroket 5y ago
I don’t. I worked on a program with hundreds of instances of the comment “do this here.” Why not just preface every line with that?
- Supermancho 5y ago
  > Why not just preface every line with that? Because that's noise that makes reading the code more difficult. Creating a separate markup file that provides comments (even overlapping) that are associated to files and lines, for display in an IDE window seems like the logical way to go from the current style of inlining comments into code.
  - emodendroket 5y ago
    I have my doubts. It seems like that would be even more likely to drift than inline comments.
    - Supermancho 5y ago

amelius 5y ago

We need a programming language that only allows writing at the bottom of the code. That way, the thoughts of the programmer become more linear, and the code becomes easier to read.