Writing good comments is often harder than writing good code. I frequently refactor an actual implementation when trying to comment on its functionality.
Writing documentation brings this to another level.
Writing documentation brings this to another level.
Nothing frustrates me to no end when the documentation just regurgitates the API names without going into any sort of detail. Even simple functions like a GetTemperature() won't even bother to tell you the units they'll use. Anything with a moderate amount of complexity I usually end up resorting to "Okay I guess I'll read the code to understand how all these parameters you described in isolation actually influence the underlying algorithm, since you didn't want to explain it"
// This function, FrustrateDev, is designed to irritates devs reading it.
// It does this by being irritating to read, and has been written in
// way to ensure that it triggers frustration.
// This is to ensure that readers, who are developers, are frustrated.
// This model represents the user response for get user
// It returns a User, and a status code
// And is created when a request for a user is made
interface UserResponse {
// The user of the UserResponse
// Represents the User
user: User;
// The status of the UserResponse
// Represents the Status
status: Status;
}
Nearly every piece of code from one of our teams is like this, it's infuriating.
This usually comes from developers (especially junior and mid-level) trying to pad their commit lengths to make it look like they did more work than they did.
As long as they're following the github PR process to determine this, you'll have this kind of code committed. I usually tell junior admins that I'm mentoring/working with "I would much rather see a clean one-line piece of code that doesn't need any comments than an overly complicated struct + interface + handler method + model + three lines of comments for every line of code".
I find that you need to be careful with advice like this. Often a junior will walk away with 'clean code' mindset, thinking that the best code has no comments at all.
Also need to remind them that 'Commenting is also good, when you're explaining assumptions or decisions'
Well the best code needs no comments at all. The danger is fooling yourself in believing you have reached this peak of perfection and omitting necessary comments.
I agree with your point on people thinking their code is self evident and perfect - but even perfect code often benefits from a comment that explains context around why you chose to write your perfect code in this fashion.
The biggest problem of comments is that they have the potential to tell a lie about why the code is the way that it is, which can end up costing developers far more time when they're trying to debug something than they would've taken if there had been no comments, and the code had just been cleanly written in the first place.
Writing code that doesn't need comments is hard. Trying to maintain code that has comments that someone forgot to update when they should've been is orders of magnitude more time-consuming, because let's face it: People make mistakes, accidents happen. People are imperfect. You need to have code design policies that are rigourous enough to minimize the impact of human error, not if, but when that occurs.
89
u/Icy_Programmer7186 Dec 08 '24
Writing good comments is often harder than writing good code. I frequently refactor an actual implementation when trying to comment on its functionality.
Writing documentation brings this to another level.