171–180 of 238 posts
I used to be a firm believer in self documenting code, but that approach often led to a large number of functions that only get called once. So lately, I have been just putting a comment line where I otherwise would have refactored the code into a function, and I feel that it has made my code a lot easier to read, and understand.
My golden rule is inline with javadoc being largly useless. Don't ever add SBO comments. SBO = Stating the Bleeding Obvious.
Sometimes, the "obvious" code has a bug, but its intended purpose is no longer obvious. Commends for "obvious" things add redundancy, like error-correcting codes.
Earlier 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?
VSCode git-lens. Mandatory extension. Either way, I think both are useful, although for documenting weird code I think code comments are more important. I the commit message you should explain why you change the code. In the code, why it works like that.
I still wouldn't use git as a replacement for comments since git history is wiped out all the time. Moving files or reformatting or a million other things could remove a critical commit message.
Earlier quoted context omitted.
Or you can write tests for every single not there case. Just bringing it up, I usually write lots more comments than tests. I also encourage my teammates to add comments. The problem is when one can't really explain why the simpler approach didn't work. That requires more research just to write the comment, but I think it pays off really quick.
Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line. I'm sure it would be possible to build such a tool, b…
Another 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…
If you have a unit test for that piece of code then that would probably help to act as a stopgap measure against attempting to "fix" the complicated-seeming code.
Rather than adding a comment saying "hey make sure you change that other section" I have test which lists the columns in the table and fails if they change. Then the person who changed it will see the comment on the test explaining why it failed and what they must do.
I use comments to break up a large block of code into smaller chunks to explain what is happening / where we are in the process. I used to be a firm believer in self documenting code, but that approach often led to a large number of functions that only get called once. So lately, I have been just putting a comment line where I otherwise would have refactored the code into a function, and I feel that it has made my co…
I was bitten many times thinking "yes, this is the equation (21) of the well-known paper, no needs to comment" to then fall flat on the nose because this was well-known to me, not the other engineers coming from another field, an assumption was there for let say a concentration of a chemical in the formula but then it was used in another context where the assumption does not make sense, etc.
For all the "bit-pushing" part of the software, opening files, reading data and so on, it is way easier to have self documenting code.
Earlier quoted context omitted.
No. Code is intended for your teammates. Compiled machine code is for your computer. If you were addressing a machine, you would be writing 0s and 1s, because o boy do the machine know how to execute those little ons & offs.
People often insist on this point, and I still don't get it. Honestly it comes across as intentionally exaggerating a claim beyond reason, in order to make it sufficiently counterintuitive to sound clever. The point of the program is to get the computer to perform some task; the way we get the program into the computer is to write code. You can say we're writing code for the compiler if you want to be pedantic; or yo…
By insisting on this, I mean that, at any given time, if I have the choice to write code that is easily readable by an human XOR a code that is easy to execute (fast), I will always choose the first.
And it’s not a dogmatic ideology : sure there are tradeoffs where writing efficient code is needed, sure it depends on the industry you work.
But in general, when needed, it’s much easier to make a readable code faster than to make a fast code easier to read.
I’ve seen so much « optimized for machine » code in my career. Probably written by really smart person who chased the millisecond perfection. But 90% of this code is « one shot execution » where millisecond doesn’t change anything and is probably wasted anyway by the surrounding framework/library/context…
I always hated that sentiment of "no comments", although I share the wish of computers understanding our code better. I think the refactoring tools didn't really live up to the promise, because they require the discipline of writing everything in the code in computer-readable format, otherwise they will leave fragments of wrong documentation in their wake. One of the benefits of human language is that you can easily create a DSL (concepts and terminology), and the refactoring tools usually cannot handle custom DSLs (much less vague ones) very well (seems like a strong AI problem).
Earlier quoted context omitted.
I also do this with optimisations, when I work on low-level code: If I come up with an inefficient algorithm that's short and readable, I tend to optimise it to something better but leave the reference implementation inside a code block. (This goes without saying, but: I don't leave "commented code", but code inside comment, generally formatted with Markdown)
Is there a reason you don't leave a comment with the commit hash of the change instead?