3 ms·
I wouldn't be as opinionated as OP. While I do agree that javadoc style comments are a curse we should get rid of, I find comments inline with code to be better
by tuetuopay 4y ago
I wouldn't be as opinionated as OP. While I do agree that javadoc style comments are a curse we should get rid of, I find comments inline with code to be better a bit tuned down. Usually, the comment is useful when you don't grasp why a particular line is there. You notice there is a comment, so you read it. It's better to get an overview of the code, then drill down to its details with the help of comments. But those did not get in the way for the initial readout to get the big picture.
IMHO it's the same reason editors offer folding functionality for code blocks. You get a big picture, then drill down to it, eliminating some clutter. For example, take Go's infamous `if err != nil { return err }`. I don't need to know every single one of them in a piece of code to get the big picture, so them being folded is good. Then upon further examination, I can expand them to see whether any special error handling is done at some place and why.
For diffing colors, that's why I prefer a good side-by-side viewer with syntax highlighting. The default unified diff output is pretty useless when more than 2 consecutive lines changed. That is something that GitLab and others get right: side by side, changes to a line highlighted to tell "hey, only this word in the line changed, but it still count as the whole line being replaced".
- cogman10 4y ago> While I do agree that javadoc style comments are a curse we should get rid of Meh, I think javadoc is somewhat antiquated but otherwise an ok markup language for documentation. I do like that newer languages seem to have switched to a version of markdown for documentation.