Self-documenting Code
Self-documenting Code
Think back to the last time you looked at an unfamiliar block of code. Did you immediately understand what it was doing? If not, you’re not alone – many software developers, including myself, find it challenging to grasp unfamiliar code quickly…
You're viewing a single thread.
Figuring out what the code is doing is not the hard part. Documenting the reason you want it to do that (domain knowledge) is the hard part.
Agreed.
And sometimes code is not the right medium for communicating domain knowledge. For example, if you are writing code the does some geometric calculations, with lot of trigonometry, etc. Even with clear variable names, it can be hard to decipher without a generous comment or splitting it up into functions with verbose names. Sometimes you really just want a picture of what's happening, in SVG format, embedded into the function documentation HTML.
Yeah. I advocate for self explanatory code, but I definitely don't frown upon comments. Comments are super useful but soooo overused. I have coworkers that aren't that great that would definitely comment on the most basic if statements. That's why we have to push self explanatory code, because some beginners think they need to say:
//prints to the console console.log("hello world");I think by my logic, comments are kind of an advanced level concept, lol. Like you shouldn't really start using comments often until you're writing some pretty complex code, or using a giant codebase.
Comments are super useful but soooo overused
I think overusing comments is a non-issue. I'd rather have over-commented code that doesn't need it, over undocumented code without comments that needs them. If this over-commenting causes some comments to be out of date, those instances should hopefully be obvious from the code itself or the other comments and easily fixed.
I understand what you're saying and I mostly agree, but those few instances where a line of code is only slightly different and the comment is the same, can really be confusing.
TempleOS: Hold my communion wine
One upvote is not enough.
I once wrote a commit message the length of a full blog post comparing 10 different alternatives for micro optimization, with benchmarks and more. The diff itself was ten lines. Shaved around 4% off the hot path (based on a sampling profiler that ran over the weekend).
I can't recall the exact change but a coworker did something five years very intentionally. The comments, the commit and everything described what they did but not why.
I think it was with side effects: true and I fixed a certain way we bundled things and I believe that could have solved the issue but I don't know for sure :/