I like comments to be an "alternative" way to read the code , e.g. understanding the flow / logic solely by reading through the comments (and only having to look at the actual implementation / code when more details are needed).
On Comments in Code
151–160 of 238 posts
Re: On Comments in Code
#152The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.
> _most_ of the time This is the thing that annoys me with arguments about all this. I will generally say "document the 'why' and not the 'what'; if the 'what' isn't clear from the code, fix the code to make it clear". And people will say "that's invalid because sometimes you really do need to do something clever and the 'what' needs to be documented" or whatever. And yes, that's fine! Stop taking everything people s…
I think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that the documentation is encoded in the function and variable names, more or less. Sure, extraneous comments should usually be avoided, but frankly, sometimes a couple sentences of plain English is just clearer. I'd rather people just tell me what's going on than try to squeeze it in to a few camel-case words if that would compromise the clarity.
Re: On Comments in Code
#153Earlier quoted context omitted.
You might as well be able to extract a method with a meaningful name then.
Please no. Don't extract methods methods just to avoid using a comment. You end up making code more difficult to follow when you do that since you're now jumping somewhere else in the file and you're adding a lot of noise by having to pass the function's current state along as arguments to the new function.
>by having to pass the function's current state along as arguments to the new function.
But then the state being read and mutated by a block of code is explicit. The alternative is having to inspect the code to determine if and what state is being manipulated. The more code in a functional unit, the harder this gets.
Re: On Comments in Code
#154Earlier quoted context omitted.
Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?
The GitHub web interface, specifically the "blame" view for a file.
That only shows the most recent commit, which is IME often not substantive, just some treewide commit like "autoformat" or "moved class into another file" or whatever. I can click on the parent commit button repeatedly until I find all the info but that's really not a good interface for exposing the history of a class.
Re: On Comments in Code
#155Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…
//
// Dear maintainer:
//
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 42
//
Re: On Comments in Code
#156Whenever I'm not clear on something I wrote, I have to spend the time deciphering it, and then add a comment to save myself the time next time.
After a while of doing this, I get a sense for what kind of stuff I'll find puzzling later and can comment preemptively.
Re: On Comments in Code
#157Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…
>Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason.
>So now I have a new rule: every time I try a simple approach and it fails and I replace it with a more complicated one that works, I add a comment explaining the previous strategy and why it didn't work.
My strategy is to comment out the failed attempt and leave it there for next time.
Re: On Comments in Code
#158Half-OT: What happened to literate programming? Back in the CoffeeScript days, it's creator adopted a literate programming format, which was basically Markdown with code blocks being CoffeeScript. He talked about that as the future of programming. Whelp, CoffeeScript got killed off by ES2015 and the file format never caught on. I know the concept of literate programming does come from Knuth, but I first heard about i…
I think many programmers are not big on writing, you can see on this thread there are a large number that object to almost any comments at all, and support the assertion with the belief that comments go stale and won’t be updated because people can’t be bothered to write. I think the appeal of no comments is the quest for perfection in the source code - that you can achieve something that needs no explanation. In contrast literate programming nakedly admits the discovery of the solution and how code was developed and its imperfection.
That said it has caught on some with data science and actually is an option with swift playgrounds.
Re: On Comments in Code
#159Earlier quoted context omitted.
I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.
Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?
An idealistic reason for encouraging longer-form commit messages is that they have the side effect of more coherent commits, making the history easier to navigate, making the history more useful, and so your workflow will probably use the history more.
A practical reason for longer-form commit messages even in modern PR workflows is that they allow you to create and view commentary on a group of changes across files without leaving your editor.
As an interface to git, nothing beats magit. Even if you never use Emacs for editing any text files, it's useful as a magit runner.
Re: On Comments in Code
#160Earlier quoted context omitted.
The GitHub web interface, specifically the "blame" view for a file.
That only shows the most recent commit, which is IME often not substantive, just some treewide commit like "autoformat" or "moved class into another file" or whatever. I can click on the parent commit button repeatedly until I find all the info but that's really not a good interface for exposing the history of a class.
Each line in the GitHub web blame interface has a little icon which, when you hover over it, says "View blame prior to this change" - I use that all the time.