About the only time I use comments are to delineate a block of code that for whatever reason can’t be a method or because I am working around some bug and I think I might be tempted in the future to remove that code as “useless”. (Think “the dispatch_main here ensures that the code runs on the next runloop iteration, which is necessary for the animation to work”.)
Code only says what it does
71–80 of 120 posts
Re: Code only says what it does
#72If I had a nickel for every programmer who thought their code was so good it didn't require comments... or thinks somehow that unit tests make up for comments... only to come back years later and have no idea why the logic is working how it is.
This was a thing at my last job. The lack of comments always made me cringe. While not every line needs a comment, there's a reason why comments would be useful, especially in security software. I learned a lot of bad habits there and I'm glad I no longer work there. Their excuses were literally "no one reads comments" "no one keeps comments up to date" "my code is self documenting" etc.
The self documenting one always gets me. It's not like the person has never read code that is difficult to understand.
Yet they think it is just other people who write 'bad' code. Their own code can't possibly be bad. In fact it is so good that it 'documents itself'. It's just a statement that drips with arrogance.
Re: Code only says what it does
#73What I’ve noticed is that code is the only medium of communication that is non-ambiguous. Designers, product people, stakeholders, etc, all use ambiguous mediums. It’s impossible to understand just how pedantic and explicit you need to be when writing code versus, say, giving your human colleagues instructions.
So it's 0% ambiguity for code. 100% ambiguity for the rest. In other words, communicating with the computer is overly pedantic, and code bares all the frustration. Can we make it more fair? 70-30 perhaps?
Rather than concentrating on mediums that help with communication (as this post mentions: Design Docs, TLA+, comments…) I want a new medium that allows me share the burden of overscrupulousity with the rest of the people in my team, and not just developers.
Re: Code only says what it does
#74If I had a nickel for every programmer who thought their code was so good it didn't require comments... or thinks somehow that unit tests make up for comments... only to come back years later and have no idea why the logic is working how it is.
It's a matter of judgement. I've read code in languages I don't know, even, where I could immediately figure out what was going on without reading any comments. I've also patched libraries in ten minutes without reading comments. It's certainly possible to write code that doesn't need comments, though perhaps, we're not the best people to judge when that's the case or not for our own code.
Same here. Though if you are putting thought into the code you are writing - the logic, the structure, etc.. Then those thoughts should probably be written down as well as comments.
Re: Code only says what it does
#75This is a major problem with code: You don't know which quirks are load-bearing. You may remember, or be able to guess, or be able to puzzle it out from first principles, or not care, but all of those things are slow and error-prone. This is a problem from both the negative (not breaking things) and positive (knowing how to add things) perspectives. The positive perspective was written about by Peter Naur in one of m…
I think I have to disagree with Naur on this, in that people using the Scientific Method don't ship their theories, but we do. As a scientist who has just succeeded in testing a hypothesis, I now need to go back and document a simplified series of steps that should lead any independent party to the same phenomenon. Once we are on the same page, they can confirm or refute my theory based on their own perspectives on t…
I think I have to disagree with you on this one, I've used the scientific method (though not in an explicit checkbox-y way) plenty of times to ship and debug code.
In particular, since (as I've said on this forum many times) I work primarily on the maintenance end of software. I don't know what the creators or previous developers were thinking, especially with more recent projects (documentation quality has really gone down hill, people call autogenerated UML diagrams "design docs", but without commentary they only reflect the state of the system, not its design). I have to try different changes based on my understanding of the system and see the consequences. That is, I form a hypothesis about what will happen if I do X, I do it, I collect the results and I've either confirmed my hypothesis, refuted it, or left it in an indeterminate state. I form another and repeat. Over time I build up a model (theory) of how the system behaves and should be updated/extended. Since I can't keep tens of thousands of lines of code in my head, let alone hundreds of thousands or millions, I always only have a model (theory), because I never have the totality of it in my mind. Though good code, with good use of modules, makes it easier to keep large chunks in mind, I still have to have a model of how those modules work and work together.
Hell, this is half (or more) of testing for older software systems. You put in some input and see if you get the output you expected. If you don't, you evaluate why (is my model wrong or is the system wrong) and repeat.
Re: Code only says what it does
#76So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why . Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to t…
> "Clear code shouldn't need comments" That's like saying articles don't need summary.
Agreed; or like saying "You don't need a map; you can clearly see where this road leads if you follow it far enough."
Re: Code only says what it does
#77Earlier quoted context omitted.
I think I have to disagree with Naur on this, in that people using the Scientific Method don't ship their theories, but we do. As a scientist who has just succeeded in testing a hypothesis, I now need to go back and document a simplified series of steps that should lead any independent party to the same phenomenon. Once we are on the same page, they can confirm or refute my theory based on their own perspectives on t…
I think I have to disagree with you on this one, I've used the scientific method (though not in an explicit checkbox-y way) plenty of times to ship and debug code. In particular, since (as I've said on this forum many times) I work primarily on the maintenance end of software. I don't know what the creators or previous developers were thinking, especially with more recent projects (documentation quality has really go…
Insofar as "what happens when I do this?" goes, it neglects the null hypothesis. If you don't pay attention to falsifiability can you claim to be doing science?
Re: Code only says what it does
#78Earlier quoted context omitted.
This was a thing at my last job. The lack of comments always made me cringe. While not every line needs a comment, there's a reason why comments would be useful, especially in security software. I learned a lot of bad habits there and I'm glad I no longer work there. Their excuses were literally "no one reads comments" "no one keeps comments up to date" "my code is self documenting" etc.
The self documenting one always gets me. It's not like the person has never read code that is difficult to understand. Yet they think it is just other people who write 'bad' code. Their own code can't possibly be bad. In fact it is so good that it 'documents itself'. It's just a statement that drips with arrogance.
Ya, but with a security product there are important considerations and while we commented on areas where we fixed a bug due to something fixable, it was a pain in general.
Decisions maybe don’t belong in code but with a security product I feel there has to be some quality level of comments to explain why and how. Someone coming along later can’t be expected to be in the authors head and the author won’t remember all this stuff years later when it might matter or need to be rewritten.
Such a shit show
Re: Code only says what it does
#79What I’ve noticed is that code is the only medium of communication that is non-ambiguous. Designers, product people, stakeholders, etc, all use ambiguous mediums. It’s impossible to understand just how pedantic and explicit you need to be when writing code versus, say, giving your human colleagues instructions. So it's 0% ambiguity for code. 100% ambiguity for the rest. In other words, communicating with the computer…
Pseudocode, perhaps?
Re: Code only says what it does
#80If you want your cake and also the ability to consume it, you might want to consider what functional programming can do for you regarding the ability of your codebase to self-document itself. Having type systems that are very closely aligned with the abstract business model is the best way to avoid frustration when you are trying to figure out why something is the way it is. The trick is understanding that functional…
I find functional code much shorter and cleaner, but also when you want to change something along a new axis you need to do a much bigger rewrite than with imperative/procedural/object-oriented code.
OO code: "here's a detailed and long-winded description of what happens that's hard to understand. Ignore 95% of it and change that 1 little detail and hope for the best"
Functional code: "here's a concise and easy to understand description of what happens, understand it fully, throw it away, and create a new, just as clear and concise description of what should happen from now on"