If your code files don’t contain more lines of comments than lines of actual code, then you’re doing it wrong. (For Python, docstrings count as comments)
And your comments shouldn’t say what each line of code is doing. If you can code, then you can already tell what each line is doing by just reading the code. The comments should explain WHY it’s being done this way, or HOW it’s being done, or highlight some pitfalls that might snare a future developer, and generally just give some higher level context to a line or block of code.
Oh fuck I hate encountering this level of commenting. If it’s complicated, you should have a design doc. Source code is not where you write your dissertation. Simple explanations are good, especially since the code could be updated while the comment is likely to remain unchanged. Long expositions are usually the result of bad coding or improperly allocated design.
Absolutely agreed. If your code line by line isn’t clear, then the code is the problem.
Commenting before a block of code (a function / algorithm or whatever) explaining what it is meant to do, absolutely that’s great though, saves time when revisiting.
And that one single line that makes zero FUCKING SENSE AND YOU SPENT 5 DAYS TRYING TO FIX IT!!! That definitely needs a comment so the next idiot (aka you in 6 months) doesn’t think “what useless shit is this? Let’s delete this!”.
Comments are for revision control systems. We have a strictly no comments in code policy because comments too often end up being wrong or misleading throwing everyone believing in them for a wild ride. The only thing that is worse than bad code is bad comments.
When you read sensible and thorough commit messages you generally have the notion that whatever it says was probably true at the time of the commit, whereas when you read comments in code it can still be correct or just plain utterly wrong.
@nthcdr this assumes that people write sensible and thorough commit messages, instead of brief five-word ones or, say, song lyrics. Both of which I’ve seen.
I at least try, except maybe for the other day where my commit message consisted entirely of an exasperated “why”, followed by a revert.
That being said, every commit message where I work is required to contain a ticket number (and the server will reject the push if you don’t) so at least there’s that for context.
Yes there need to be some assumption that your co-workers write reasonable commit message even if they have their lapses now and then.
Another problem with comments in code is that they tend to be short because nobody likes to read code interspersed by walls of prose. But many times if something really needs explaining you also need a little more room doing it. Thus when committing in code people tend to gloss over important detail.
Then of course there is literate programming. The other end of the spectrum, but then we’re talking code in documentation not comments in code.
I left the company, worked at other places in other languages, the company restructured, moved to India and back, got new premises, headhunted me because someone remembered that I wrote this particular system (serial port controller for certain industrial machinery). When revisiting code that I wrote 15 years ago, I was glad that my comments explained what I was doing, and why, and how, because all the other documentation was long gone. Don’t imagine that the original design documentation will still exist when you come back to it.
If your code files don’t contain more lines of comments than lines of actual code, then you’re doing it wrong. (For Python, docstrings count as comments)
And your comments shouldn’t say what each line of code is doing. If you can code, then you can already tell what each line is doing by just reading the code. The comments should explain WHY it’s being done this way, or HOW it’s being done, or highlight some pitfalls that might snare a future developer, and generally just give some higher level context to a line or block of code.
@257m @programming
Oh fuck I hate encountering this level of commenting. If it’s complicated, you should have a design doc. Source code is not where you write your dissertation. Simple explanations are good, especially since the code could be updated while the comment is likely to remain unchanged. Long expositions are usually the result of bad coding or improperly allocated design.
Absolutely agreed. If your code line by line isn’t clear, then the code is the problem.
Commenting before a block of code (a function / algorithm or whatever) explaining what it is meant to do, absolutely that’s great though, saves time when revisiting.
As long as it’s updated when the code changes
And that one single line that makes zero FUCKING SENSE AND YOU SPENT 5 DAYS TRYING TO FIX IT!!! That definitely needs a comment so the next idiot (aka you in 6 months) doesn’t think “what useless shit is this? Let’s delete this!”.
@TerrorBite @257m @programming
Comments are for revision control systems. We have a strictly no comments in code policy because comments too often end up being wrong or misleading throwing everyone believing in them for a wild ride. The only thing that is worse than bad code is bad comments.
When you read sensible and thorough commit messages you generally have the notion that whatever it says was probably true at the time of the commit, whereas when you read comments in code it can still be correct or just plain utterly wrong.
@nthcdr this assumes that people write sensible and thorough commit messages, instead of brief five-word ones or, say, song lyrics. Both of which I’ve seen.
I at least try, except maybe for the other day where my commit message consisted entirely of an exasperated “why”, followed by a revert.
That being said, every commit message where I work is required to contain a ticket number (and the server will reject the push if you don’t) so at least there’s that for context.
@257m @programming
@TerrorBite
Yes there need to be some assumption that your co-workers write reasonable commit message even if they have their lapses now and then.
Another problem with comments in code is that they tend to be short because nobody likes to read code interspersed by walls of prose. But many times if something really needs explaining you also need a little more room doing it. Thus when committing in code people tend to gloss over important detail.
Then of course there is literate programming. The other end of the spectrum, but then we’re talking code in documentation not comments in code.
@257m @programming
I left the company, worked at other places in other languages, the company restructured, moved to India and back, got new premises, headhunted me because someone remembered that I wrote this particular system (serial port controller for certain industrial machinery). When revisiting code that I wrote 15 years ago, I was glad that my comments explained what I was doing, and why, and how, because all the other documentation was long gone. Don’t imagine that the original design documentation will still exist when you come back to it.