Submitted 11 months ago by Asudox@lemmy.world to programming@programming.dev
I just recently started documenting my code as it helped me. Though I feel like my documentations are a bit too verbose and probably unneeded on obvious parts of my code.
So I started commenting above a few lines of code and explain it in a short sentence what I do or why I do that, then leave a space under it for the next line so it is easier to read.
Your code should generally be self documenting: Have variable and method names that make sense.
Use comments when you need to explain something that might not be obvious to someone reading the code.
Also have documentation for your APIs: The interfaces between your components.
One interesting thing I read was that commenting code can be considered a code smell. It doesn’t mean it’s bad, it just means if you find yourself having to do it you should ask yourself if there’s a better way to write the code so the comment isn’t needed. Mostly you can but sometimes you can’t.
Agree with you though, generally people should be able to understand what’s going on by reading your code and tests.
Great points. I’m a huge advocate for adding comments liberally, and then treating them as a code smell after.
During my team’s code reviews, anything that gets a comment invariably raises a “could we improve this so the comment isn’t need?” conversation.
Our solution is often an added test, because the comment was there to warn future developers not to make the same mistake we did.
I know there are documentation generators (like JSDoc in JavaScript) where you can literally write documentation in your code and have a documentation site auto-generated at each deployment. There’s definitely mixed views on this though
To my knowledge that just formats existing comments. With LLMs you could probably do 95% of the actual commenting.
Good comments describe the “why” or rationale. Not the what. This function doesn’t need any comments at all… but it needs a far better name like logAndReturnSeed. That said, depending on what specifically you’re doing I’d probably advocate for not printing the value in this function because it feels weird so I’d probably end up writing this function like
def function rollD10() -> int: return random.randInt(1, 10)
And I, as a senior developer, think that level of comments is great.
You mentioned that this is a trivial example but the main skill in commenting is using it sparingly when it adds value - so a more realistic example might be more helpful.
The big problem in your code is that the function name isn’t descriptive. If I’m 500 lines down seeing this function called, how do I know what you’re trying to do? I’m going to have to scroll up 500 lines to find out. The function name should be descriptive.
I find too verbose comments less annoying than no comments.
Try to describe the bigger picture. Good comments allow understanding the current portion of the code without reading other code.
Also add comments later if you find yourself having to read other code to understand the code you’re currently looking at.
Comments are also a good place to write out abrevations/acronyms.
Never optimize for sourcecode size.
I expected this comment section to be a mess, but actually it’s really good.
If you want an example, look at the Atom codebase. It is incredibly well done.
Great summary. The only thing I would add is that when we say “Answer Why?” we’re implicitly inlcuding “WTF?!”. It’s the one version of “what” that’s usually worth the window line space it costs. - Usually with a link to the unsolved upstream bug report at the heart of the mess.
I’m curious as to thoughts regarding documenting intent which cross over with what in my opinion.
Regarding self documenting: I agree, but I also think that means potentially using 5 lines when 1 would do if it makes maintenance more straightforward. This crazy perl one liner makes perfect sense today but not in 3 years.
I like to do two kinds of comments:
There is no need to explain what every line of code is doing, coders can read the code itself for that. Instead focus on what part of the overall task a certain chunk of code is handling.
I rarely read comments in code, that is from within source code anyway. I of course write comments explaining the behavior of public facing interfaces and otherwise where they serve to generate documentation, but very rarely otherwise. And I use that generated documentation. So in a roundabout way I do read comments but outside of the code base.
For instance I might use godoc to get a general idea of components but if I’m in the code I’ll be reading the code instead.
As others have said, your code generally but not always should clearly express what it does. It is fine to comment why you have decided to implement something in a way that isn’t immediately clear.
I’m not saying others don’t read comments in code; some do. I just never find myself looking at docs in code. The most important skill I have cultivated over the decades has been learning to read and follow the actual code itself.
For new code I’m writing I’m using mostly JsDoc function headers where on public methods of classes and exported functions. With one or two sentences explaining what function does.
Also try to explain what to expect in edge cases, like when you pass am empty string, null, … stuff of that nature - for which I then create unit tests.
I also always mention if a function is pure or not or if a method changes the state of a class. On a sidenote I find it odd that almost no language has a keyword for pure functions or readonly methods.
What is a pure function? Never heard that before.
Essentially a function that doesn’t produce side effects, like modifying variables outside of its scope or modifying the function parameters. This something you should always try to incorporate into your code as it makes it much easier to test and makes the function’s use less risky since you don’t relay on external unrelated values.
To give you an example in JavaScript, here are two ways to replace certain numbers from an other list of numbers with the number 0
first a way to do it with a non pure function :
let bannedNumbers = [4,6] const nums = [0,1,2,3,4,5,6,7,8,9]
function replaceWithZero(nums){ for (let i = 0 ; i < nums.length; i++){ if (bannedNumbers.includes(nums[i])){ nums[i] = 0 } } } replaceWithZero(nums) console.log("numbers are : ", nums)
here the function replaceWithZero does two things that make it impure. First it modifies its parameter. This can lead to issues, for example if you have Second it uses a non-constant variable outside of its scope (bannedNumbers). Which is bad because if somewhere else in the code someone changes bannedNumbers the behavior of the function changes.
A proper pure implementation could look like this :
const nums = [0,1,2,3,4,5,6,7,8,9] function repalceWithZero(nums){ const bannedNumbers = [4,6] const result = [] for(const num of nums){ result.push(bannedNumbers.includes(num) ? 0 : num) } return result } const replaced = replaceWithZero(nums) console.log("numbers are : ", replaced)
Here we are not modifying anything outside of the function’s scope or its parameters. This means that no matter where, when and how often we call this function it will always behave the same when given the same inputs! This is the whole goal of pure functions.
There are several types of documentation:
zarlin@lemmy.world 11 months ago
The code already describes what it does, your comments should describe why it does that, so the purpose of the code.
Carighan@lemmy.world 11 months ago
Yeah, my general rule of thumb is that the following 4 things should be in the documentation:
MagicShel@programming.dev 11 months ago
Yep. I mostly document why the obvious or best practice solution is wrong. And the answer is usually because of reliance on other poorly written code - third party or internal.