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…
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).
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.
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 :/
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.
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).
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.
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 :/