As I am involved in more low level stuff, I prefer to read the source than the man pages, and I am very happy with people overcommenting their code as a user of e.g. a lib. On the other hand, it is unbearable to me to see comments on a codebase I am working on. Fortunately, emacs show/hide comments exists, so I find myself overcommenting things.
Maybe comments should explain 'what' (2017)
91–100 of 212 posts
Re: Maybe comments should explain 'what' (2017)
#92I feel like no one serious uses the uncle Bob style of programming anymore (where each line is extracted into its own method). This was a thing for a while but anyone who's tried to fix bugs in a codebase like that knows exactly what this article is talking about. It's a constant frustration of pressing the "go to definition" key over and over, and going back and forth between separate pieces that run in sequence. I…
For an example of what happens when he runs into a real programmer see: https://github.com/johnousterhout/aposd-vs-clean-code _A Philosophy of Software Design_ is an amazing and under-rated book: https://www.goodreads.com/en/book/show/39996759-a-philosophy... and one which I highly recommend and which markedly improved my code --- the other book made me question my boss's competence when it showed up on his desk, but…
Each page in that book serves its purpose. That purpose is raising the monitor 0.1mm.
Re: Maybe comments should explain 'what' (2017)
#93Sometimes I want to use comments because I'm doing something vaguely algorithmic, and I know some readers won't follow the code. I'm trying to think of a good example, maybe something like a pointer window based function (off the top of my head) (This isn't real code. Don't get hung up on it) func DedupeStrings(ss []string) []string { if len(ss) People will quibble, but - I'm not convinced you could change the variab…
What is ss supposed to mean? Also, I only know what "u" means because of your "uniques" comment. Those comments also don't really help me quickly understand the code. I'd do a small doc comment along the lines of "Removes repeated elements from the supplied list, returning the remaining items in original order"
[deleted]
Re: Maybe comments should explain 'what' (2017)
#94bug workarounds don't need to be justified if instead of working around the bug you just fix it instead.
Sure, but you can't always fix the bug if it's not in your system.
Fork it, you should have ownership of your whole stack.
If you have the spare time, you can try and submit your patches upstream; in the meantime, you just maintain your own version.
Re: Maybe comments should explain 'what' (2017)
#95Explain "why not what" is good general advice. My further advice for comments is: even bad comments can be useful (unless they're from LLM output maybe...) therefore when in doubt, write a comment. Write it in your own words. Had to add the last sentence for the circa 2020s developer experience. LLM comments are almost never useful since they're supposed to convey meaningful information to another human coder, anythi…
I always think LLM comments are more about helping themselves to stay on track.
Same goes for human comments tbf
Re: Maybe comments should explain 'what' (2017)
#96Sometimes I want to use comments because I'm doing something vaguely algorithmic, and I know some readers won't follow the code. I'm trying to think of a good example, maybe something like a pointer window based function (off the top of my head) (This isn't real code. Don't get hung up on it) func DedupeStrings(ss []string) []string { if len(ss) People will quibble, but - I'm not convinced you could change the variab…
I'll be honest, this code is easier to read for me without the comments. Also sorting feels like it's going to be slower than having some kind of set structure? You don't need ordering, just collocation of duplicates. If not or if it's a wash, that is also a good thing to comment. Also I'm not sure about the semantics of Go but it seems this mutates the argument AND returns a value, something I consider dangerous. Ot…
[deleted]
Re: Maybe comments should explain 'what' (2017)
#97I made a point here https://antirez.com/news/124 that comments are needed at the same time for different reasons, and different comments have differente semantical properties that can be classified in classes you very easily find again and again, even in very different code bases.
Re: Maybe comments should explain 'what' (2017)
#98I feel like no one serious uses the uncle Bob style of programming anymore (where each line is extracted into its own method). This was a thing for a while but anyone who's tried to fix bugs in a codebase like that knows exactly what this article is talking about. It's a constant frustration of pressing the "go to definition" key over and over, and going back and forth between separate pieces that run in sequence. I…
For an example of what happens when he runs into a real programmer see: https://github.com/johnousterhout/aposd-vs-clean-code _A Philosophy of Software Design_ is an amazing and under-rated book: https://www.goodreads.com/en/book/show/39996759-a-philosophy... and one which I highly recommend and which markedly improved my code --- the other book made me question my boss's competence when it showed up on his desk, but…
That's a really interesting read. I felt myself being closer to John about the small method part, but closer to UB for the TDD part, even if in both cases I was somewhere inbetween.
At the very least, you convinced me to add John's book to my ever-growing reading list.
Re: Maybe comments should explain 'what' (2017)
#99[flagged]
What you describe really is describing the "why", not the "what".
The line between the two is not that blurry: assume your reader has total knowledge of programming, and no knowledge whatsoever of the outside world. Comments about what the code does to bits are the "what"; comments about how the code relates to the outside world are the "why". The rest is a matter of taste and judgment.
Re: Maybe comments should explain 'what' (2017)
#100[flagged]
I always use “what” comments for regular expressions, in addition I provide examples of before and after transformations so that future developers know immediately what’s going on without having to first stop, context-switch, and decipher hieroglyphs.
This is probably one of the best use cases for "what" comments... however in my opinion a much better way to go about this is to have example-based tests (and maybe a decent function name) serve as your documentation.