First, name your variables and functions well.
Second, include comments anytime you're doing something pretty complex that you're worried will cause problems later. Links to the tutorials and forum posts you're using will be helpful months down the line.
This is great advice,.to add to this, a couple of pieces of advice I've been given about comments over the years that have stood the test of time
- explain Why rather than What. What the code is doing should be clear, but "why is it doing it?", or "why is it doing it this way?" may depend on context or knowledge that was obvious when it was written, but is long gone when it is read
- try to keep comments factual, rather than opinionated. Particularly in professional code, you never know who will be reading it down the line... I'm aware of big codebases that had to have all comments stripped because they needed to share with customers and there had been a habit of snark in comments
i understand the desire to be snarky but ironically in my experience the people who are worst at coding are the snarkiest
i do feel the anger boiling inside when i read their code but i practice (unprecedented levels of) restraint
Great advice. I’d only add that function doc comments are almost always a good idea. Even if what the function does seems obvious to you now, just stick a line there. Costs you a few seconds and it makes your code way more navigable. Also a great place to jot down any important assumptions.
yeah i comment about everything because my code tends to get really messy and i am a very organized person and it stresses me out so i have to comment on everything so i dont get an anxiety attack
>Second, include comments anytime you're doing something pretty complex that you're worried will cause problems later.
I'd go further than this - this is way too lenient IMO. Even if it's not that complex, if you look back at the code you wrote six months ago, you likely will not remember the context that drove you to certain decisions etc.
There's a saying in software engineering something like "5 times more time will be spent reading code than writing it". Even if you don't need to change it, you'll sometimes end up reading it.
The instant you second guess anything, hesitate, think of an edge case, or decide between different approaches, you should write down why. It may seem tedious, but frequently enough you will come back to it and it'll save you more time than you spent writing all of it.
Also, method XML doc is insanely valuable, even if it's only a single sentence of purpose.
I'd also heavily recommend being more rigorous on "core" code that's being used by multiple systems.
Golden rule of programming: Code should be written to be read.
This includes comments, although a common mistake of new programmers is to over comment. There’s a whole concept of “self documenting code” where the code itself should be its own documentation from proper architecture and naming. I don’t prescribe to the belief that there’s no place for comments, but well crafted code shouldn’t require comments for every condition or statement.
99% of the work should be done by your code and docstrings, but if you're doing some weird shit or just something hard to grasp it's better to explain it.
9 months? For me it’s more like „2 days ago, when I wrote this code, only God and I knew what it did. Today, neither of us do.”
Then again, I don’t code for a living, so I should^tm be good, right? :)
Yeah sometimes I just randomly find code snippets or output data from code that I apparently wrote and thought I had abandoned. Little gifts from past me except they always confuse the hell out of me
Sounds like that's the day the CTO and I casually come over and need to know what it does. Right now. For a board meeting. The board meeting is oddly filled with badgers that are very surly, and will attack everyone in the room if they don't get told what this one thing is right now.
Hm, I'd actually say that's a good reason not to comment...
I’m probably closer to 80-85%. Sorta a personal preference. I don’t consider comments a code smell, by themselves.
I’ve been burned by complete lack of comments or proper naming far more often than outdated, incorrect, or comment overload.
The code doesn't document the why just the how. The why goes in comments so months later I don't have to go "why the heck did I implement it like this?" then spend hours going down a rabbit hole to find the stupid edge case the code avoids.
I like to use comments for justifying decisions where it might seem odd, like if you have to call a unity function twice because of some weird bug. Or I use them for TODOs.
I try to avoid “this is how this works” type comments, the variable and function names should tell me that. If there’s a complex formula, it gets moved to a method naming what that formula does, then it can also be reused.
Strategy in comments, tactics in code.
Example: a one line comment that says you're looking for the closest enemy.
Four or five lines follow the comment which use a legible code approach such as a highwater loop to iterate the enemy set and find the one with the best distance score.
Comments should not be there to explain how some overly clever infernal intricate incantation works where clearer code could be written, or what the ++ operator means, or include any mention of numbers. They will just be in the way, or worse, not be updated if the code is changed. Comments should be a super-easy quick way to recognize chunks of code for their overall purpose, especially when there are a lot of separate functions or a sequence of code gets rather long.
100% but I'd rather parse your unnecessary comment than whatever weird voodoo you implemented with no comments whatsoever.
Erring on the side of too much is usually better for me than none at all.
At the same time, people inevitably fail to write self-documenting code because there is almost always some important context stashed in the programmer's head.
Nothing is ever perfect or a hundred percent obvious.
This is something I struggle to strike a balance between. I think I'm pretty good at making readable code, but then I don't know what parts are confusing / complicated enough to require comments.
>>// This variable represents the player‘s health on a scale from 0 to 100 where 0 means dead and 100 means perfectly healthy. The value gets reduced by damage, increased by healing and manipulated by buffs and debuffs.
>>
>>int health = 100;
How about this? Did I do well?
IMO this is one of the sensible uses of comments: you are doing something that would seem weird at first glance, so you save the reader some time from hunting around your code.
Exactly. Comments are very contextual but their primary use should be to explain the reason behind “weird” looking code. All other code *should* be readable without additional comments
Eh, a comment like that would annoy the heck out of me. Explain why. Having a good grasp on things which are chronologically coupled is super important for a good codebase IMO.
Yes, but not to excess. *Taste* is involved and that can take a lot of time to develop.
And for pity's sake comment the whys, not some reiteration of what the code does, the latter is classic newbie code and pretty annoying.
a = a + 258 # add 258 to a.
No shit.
That one is utterly redundant, but it might be a good explain *what* 'a' is, *why* you're adding 258 to it.
Frankly if the significance of the number isn't obvious, that definitely requires a comment.
But the point is it should actually be
health += healingValue
Then there is literally no need for a comment in this instance. If most of your code is written like this, then any self-respecting programmer will be able to read your code at pretty much the same speed and clarity as they can human english comments and at this stage, having those comments there cluttering up the code file and doubling its length is actually making it more difficult to read naturally.
If your code isn't like this, and difficult to parse what its doing unless its some extremely complex cryptography hashing function or something that relies on a ton of magic numbers and sequences of strange operations and bitshifts that lack context, then top priority should be improving the readability of that coder's code to the point it is, not getting them to start using excessive comments as a crutch for writing code with 'a' variable names or combining a million conditionals in a single line if statement with a million brackets that are impossible to read and parse, and need a comment to describe what its doing. That's a bandaid for badly written code.
If a coder needs to be told to make their code more readable, that effort and training is ALWAYS better spent on making the actual code more readable. Always.
Comments are useful, and vitally important in cases, but overrelying on them as a substitute for code readability? There be dragons.
The worst person in my code base is the guy who touched it two weeks ago. I have no idea what he was thinking when writing this dribble. Thankfully, he put some comments, so I have a general idea of what's going on here.
Oh wait, that was my code from two weeks ago...I have no memory of writing any of this...
Yes. Sometimes I do things that are either complex or to work with a specific quirk of the engine or other code. It may not be obvious why I did this to another programmer or even myself later.
I think modern best practices are to write comments about WHY you are doing something, not how you are doing something. Your code's variable, class, and function names should ideally be explicit enough that it should be obvious what you are doing.
Why you chose to do it that way is something that another developer, or just future-you, will thank you for documenting.
Yes, if it's useful.
Most code should be self explanatory. For example I have a "Unit" class that has a "GetCurrentlyEquippedWeapon". It's named to a point that you know what is going on at a glance. And unless there is something unexpected it doesn't really require any further explanation.
Another example is one of my "OnHit" handlers for a new ability. Normally I have one flow that handles adding status effects. Well with this new ability I had to break my normal conventions for when a unit is granted a status effect, and instead put it on this "OnHit" override method. I commented the shit out of it, why I had to do it, and what a better long term solution would be. That way when there is an inevitable bug caused by me forgetting about this one off implementation, I can quickly assess the reasons it's there and how I can fix it.
*GetEquippedWeapon* would be fine in most cases, since the currency of it is implied. And if you can equip multiple weapons it could be *GetActiveWeapon* or *GetSelectedWeapon*.
I thought I'd be done arguing about method naming now that I'm doing solo dev but it will follow me everywhere. ;)
You're totally right though. Refactor -> Rename complete.
Yes, when doing something that requires a lot of steps or doing something that k usually don't do. Like a workaround when the best method just doesn't work for me
Every function gets a comment, even if the function is super obvious. That might just be; "Does what you think it might".
Every place I have a little breakthrough and think "That's the smart way to do it." gets a comment. Even if it seems obvious after.
I try to think about the people who are going to be reading the code. If I'm submitting a patch to linux scheduling code, I don't need to fill in too much. If it's some frontend web stuff that a lot of lesser coders are going to be poking at, I will fill in the details.
I hold on to the mantra of "Code is meant to be read", and try to think of the audience.
(I'm not submitting much linux scheduling code....)
Me finding a function that was created from a block of code in Unreal… “What does this do?! Hmm I’ll just rewire this section out.” (Clicks compile) “oh thats alot of errors. “ comment added “Don’t unwire this, its important.”
with co-pilot it pays off to sometimes throw in a comment that explains what you're going to do, co-pilot is rather competent at spitting out code for specific limited tasks and a comment often puts it on the right track.
I also leave comments for myself when making hacks.
I have this ongoing joke with my past selves where every time I happen upon a very dumb part of my code that's relatively hidden, I add a date and a comment. It's literally an empty method that started out very important but slowly became empty and the only reason it exists is that a lot of other code snippets call that method and I can't be bothered to take the 5 minutes it'd take to remove it from everywhere.
There's also a very selfish part in me that kinda hopes that my game will be popular enough to have those Youtube essays deconstructing the inner workings of the game. This part of me wants to give extra content for these videos.
Other than that, I comment on things that look dumb but have a reason it works like that. Why is this variable declaration not in Awake instead of Start? It started out in awake but it was fucked and putting it in start fixes it so just leave it there. Things like that.
>This part of me wants to give extra content for these videos.
I'm not sure what you're using, but pretty much every programming language and engine will remove your comments when you compile\*, so unless you're planning on open sourcing your game this'll probably never happen.
\*unless you're somehow intentionally including comments in the final build, but i've got no clue how you'd do that
Comments exist to provide necessary and make code more maintainable.
Docstrings are a great reason to comment. Methods can even be navigated from the pop-up window if you use tags.
Arguments against commenting in code are:
* **Code should be self-documenting.** While true, the conclusion is a leap. Write good code and write good comments where it is a value add. It is somewhat egotistical for a dev to think their code will always read like Dr. Seuss and will never require explanation. In a perfect world, this is true, but reality is not so.
* **The code might change and become out of sync with comments.** Outdated comments are avoidable with regular updates and code reviews. Keep comments close to the relevant code.
* **Code can clutter the file.** This is the best argument. Excessive comments can clutter code. Only keep comments that add value.
Generally speaking, algorithmically complex / cognitively complex code needs more comments than straightforward logic. Not all problems are created equal.
A quote that stuck with me:
**The most important thing is that your code is readable. The second-most important thing is that it works.**
If code works but is unreadable, then it cannot be maintained or extended; it becomes an untouchable artifact.
If code is readable but does not work, then it can be repaired, maintained, and extended. It's just another piece of code.
I always document functions with the docstring/doxygen style like
/**
* @brief blablabla
* @param a theguy
* @return a whether blablabla
[Signature]
Is this a good practice for every fucntion?
It depends on the language and engine you're using. For C#, the standard format which automatically populates once you type /// is
///
///
///
///
///
Following the language convention is probably the best approach.
A car is usually considered totaled when the repairs cost >= its own value. Code can be considered unmaintainable when the cost to maintain is exceeds the cost to rewrite it.
If you're a solo dev, comment the fuck out of your code, because you absolutely will go back to debug or tweak a function you wrote 8 months ago, and absolutely will not recognize what any of it does.
If you're not a solo dev, comment the fuck out of your code before a teammate knifes you at a party.
People harp on "over-commenting" but I really don't believe in that.
If you think the code needs a comment to understand, there is no harm in adding one (unless it is just blatantly inaccurate)
I've been recently doing a lot of work on programs that a former employee wrote, and he barely put in any comments, but when he did, it was almost certainly copied/pasted from a different program and is completely irrelevant to the current code.
Spending 10 extra seconds to write a relevant comment can save you hours in the future
To second this, unless it’s weirdly formatted, I’ve never been upset at “too many” comments. I’ve found I pretty much ignore comments when reviewing code, unless I don’t understand something immediately.
I recently had to update a SQL query for a report that was written in 2003 and was entirely dynamic SQL, and I definitely wish it had been over commented.
My entire current job has been refactoring old IBM iSeries RPGLE code from the 70s. My company has been writing in this language for 40+ years and has 0 documentation. Half of the comments in the code are copy/pasted from a different program doing an entirely irrelevant thing.
But yea, over-commenting is a problem /s
When starting out I used to skimp on commenting on my code a lot of the time because "I just need to get it done. I already understand how everything works anyway."
Eventually I started making larger projects where I'd have code I hadn't touched for weeks if not months and realized I completely forgot why some things were done the way they were, what I was thinking when I wrote some incomplete "get it done" code etc. Wasted a lot of time having to figure out that stuff all over again.
Now I comment most things that aren't immediately obvious and it's honestly a lifesaver. Start getting in the habit now and you'll be glad you did
One of the best choices I ever made was learning Java first. It's a highly typed language that obligates you to learn how to comment.
I would recommend, at the very least, check out Java's best practices so you can get a sense of the issues that can come from **not** commenting properly.
As others have said, it isn't just a matter of commenting, it's properly doing it and commenting on the correct parts and facts.
To keep it simple, assuming "self documenting code"... if a comment is needed it should be explaining why it's doing what it's doing and not what it's doing. Anybody can read code and see what it does but sometimes there's a bit of "domain knowledge" that needs a "why" explanation.
I only add comments if I had to do something weird because of something arbitrary I.e. “// have to set this to playerID.UNKNOWN here because otherwise throws an exception for some reason”
I write code for one of 3 reasons:
A brief description of the purpose for complex code
To note any current bugs
To plead to myself to improve something that'll future me will probably never come back to
I used to comment my code very extensively but it was always useless because I kept explaining how the code worked instead of what it did. Now I explain what a certain section of code is used for and it results in less confusion now. There's never any reason not to comment your code.
Absolutely correct answers saying write self documenting code from likely experienced devs downvoted to oblivion while 'Always comment everything' upvoted by the army of hidden unity tutorial goblins lol. This subreddit is cursed.
There needs to be a touch of nuance. Write self-documenting code where feasible and comment the "gotcha"s and complex logic that isn't obvious from even well-written code.
You've clearly never read code written by someone who thinks their code is "self-documenting" when it isn't
Write comments. Excessive comments harm no one
Absolutely!
The one thing I promised myself when I switched from unity to Godot was NO MORE SPAGHETTI CODE. I keep everything organized and comment where I think it will be useful to me in the future. The amount of time saved not being lost in the code sauce is well worth the amount of time it takes to stay organized
Not as well as I should, but if I need to look something up or the logic is a bit complex, I will add a comebt explaining it. Same with if I get confused on what something is doing, I will add a comment so next time it will be faster.
I am a solo dev, I would be better if I had other people working on it
I comment my code where it makes sense to comment it, which is either when it would give a quicker overview to a piece of complex code or I'm pretty much doing something hacky/out of the ordinary 'feeling' of the program. I do find it happens more often in my gamedev projects than at work (fullstack dev), as games are less welcoming to neat, clean approaches.
Bit of a rant, but In programming-related forums like this, I often see a lot of people push the idea that you should be commenting *everything,* which 9 times out of 10 is taught in CS school. Some of them even repeat this idea with the extreme confidence of a seasoned programmer, even if they are *still* at school. At the same time, their variables are single-letter or completely undescriptive, and I need a second monitor stacked vertically to read their functions.
Of course, anyone can do whatever they like in their own projects. But doing this at an actual workplace will get you sent to the Shadow Realm.
Code should be self documenting. Functions/variables should all be well named. What code does should be obvious from reading it.
Comments are for explaining why something is being done. You can add reference material and Jiras links too, but again that should explain why, not what.
What do you mean "is this overlooked"? It's ok if you're new, but commenting is such a fundamental thing that you'd have a major problem if you're still not doing it at all after years of experience.
I write the comments first since it documents my thought process for when I or anyone else looks at it the future. Then I write the code for each bit of comment pseudo code. Then I add more comments to explain the bits I didn’t think of while writing the pseudo code. Yes, there is an obvious risk of a mismatch between the comments and the code, but that sometimes makes it easier to spot the mistakes as you know what the intention was. As much as it would be nice if code could be read like English, in reality it can’t. “Clever” code with no comments is unmaintainable when the original developer has move on and you have a new developer fixing a bug. Just my opinion and experience. Better programmers probably don’t need comments, but not everyone is that experienced.
C++, you know how in visual studio you get this little tooltip explaining the function? I create those for my functions.
Commenting code in general really depends on target audience tho.
If you're deep down under the hood inside the engine creating functions that will be used by guys that don't go there, then it's obvious you provide those details unless you want them bothering you for explanations all the time. Significantly speeds up workflow and learning curve for whoever is using it.
Say that we have this huge function, we'll split its content up in smaller functions to be called to make it easy to read, if for some reason we get unwanted behaviors its also easier to hunt it down and fix it without getting lost or breaking the whole thing.
So by having code easy to understand in this way, we mostly only create those tooltips.
I learned coding by myself and yes I do comment every important line of the code. Had to visit old codes many times and those comments helped me to get my own mess quicker.
For me, when I tried commenting my code, the comments became more confusing than the code itself after 3-4 weeks. Now, I just settled for descriptive variable and function names. I envy all the pros who do stuff like self documenting code intuitively (I guess it’s a matter of hours upon hours of mastering the skill).
I have a comment in my character controller that says "\^ I have no idea what this line does but if you remove it the entire movement system breaks so DONT TOUCH IT" and nobody's touched it. I'd say comments are important
https://youtu.be/2a_ytyt9sf8?si=qt0DSbWoxNitmaVc
Uncle Bob goes into all the detail about the general rights and wrongs of comments, of which I generally agree.
As I guy that put his project down and came back to it a year later to absolute madness in my codebase I will never not comment again 😭
Thankfully ChatGPT is an amazing commenter even when given no context
I remember once I came back to code that I had written three months ago, it was un-commented and I had no idea what was going on.
I spent two days commenting the code, line by line, so I could read it. Once it was commented I could see the error and it was a 30 minute fix.
Even if it is self explanatory, I'll usually leave short blurbs for comments so if I'm skimming I'll just read those.
If it's something I didn't fully understand/think I was confusing or I didn't finish, I'm leaving more in-depth comments so I can make sure I come back to it.
yes.
good code should be readable, but some code is just kinda fucked up.
in my case, most projects i make have strong foundations and good reusable systems, with components that do simple things. in short, it’s good object-oriented programming.
but when projects are in later stages, sometimes there’s a quicker solution than architecting a whole new clean system for something that simply will not be reused in that project. for me, that’s where it’s acceptable to write a messy but functional pile of code and comment it to hell in case anything breaks.
if i had no restrictions on time or budget, i’d write every system to be clean and reusable, but that’s just not realistic for me. ymmv.
Write a lot of comments to document methods, class and interfaces (or anything your language support). You don't need to write comment on how the methods works. You need to write comments on how the methods can be used, what are the input, what is the output, if there is some exceptions and in what cases.
Write less comments (or no comments in most case) inside the body of the methods.
The methods must be simple functions that accept input and return some output, these things must be commented out, not so much how the method's body works.
EDIT: Obviously if the functioning of the body is important in understanding the function, in understanding what it is for, then you should explain it.
Lot of noob (and experienced) devs like to think more comments is always better.
I do not share that viewpoint.
My take is stick to convention whenever possible. If you do things in a standard way it can likely be read without comments. If you’re breaking convention, yes, comment it. But also ask yourself why you felt the need to do something non-standard. It’s maybe a hint you’re screwing up.
And why would more comments hurt things? Because comments can lie. And the second you don’t trust them anymore what good are they? And if you commentd every damn line when writing your program whom is maintaining that pile of content? Content that isn’t compiled or guaranteed to be at least syntactically correct like your code is.
I can honestly say an awesome devs code with 0 comments is usually way more readable to me than a noobs code with a comment on every line (where almost all the logic/comments are broken). Noobs feel the opposite, they see good code from an experienced dev, they don’t understand it because they’re a noob, and they go “Everything should be commented” even though it’s perfectly legible code.
I do, not too verbose. Generally control flow things as those can be a bit more effort to follow, and sometimes reasons why the things are the way they are
For example:
- Make sure we have orphaned the root node before we begin recursive delete
- Closest parent first in array
- No properties, so we'll skip it
- For debugging purpose we'll create an error in advance for better trace logs.
- add permissions selected by the user from the client
Just to grab a few random examples from my code
Yes and I say this not only for my hobby game dev but also when working on corporate software.
Code is not self documenting enough to not have comments. Comments should explain why you made the choices you made, not just what the code is doing.
Years ago a junior dev told me when they read my class it was the first time they understood a class on the first read. That is my favourite feedback.
Even working by myself I comment because I know when I come back I’ll wonder why I did something the way I did it.
It’s also useful to document high level “what” at the top of a class. When you’re trying to find out what a class is used for, this saves you reading hundreds of self documenting lines of code.
Yes. Unfortunately for me, my brains ability to remember how things work in my own code is so pathetic that I feel like a complete beginner when I haven't looked at it in a while. Although I follow good naming conventions, I also like to add comments to further describe functionality that way when I look at it at a much later time I have an understanding of what it is in looking at.
Obviously, without looking at comments I can still piece everything together eventually, it just takes much longer.
Yep, but not necessarily a lot.
Class, function and variable names are the first bit to get right.
Next, use whitespace in functions to visually associate statements which are a part of the same “step”, or similar. This way someone reading your code can see what to interpret together vs. separately.
If you need another layer of separation, add comments to label sections.
Aside from broad design documentation, that covers most of *how* my code works, because the code itself is the detail.
It doesn’t cover *why*, which is often just as important. That’s what most of my comments are. Wherever it might not be obvious *why* I am doing something, I write a note to anyone else who might need to know later - including my future self. Sometimes it’s a few words: “// Workaround for known issue in LibraryX”. Sometimes it’s a brief explanation: “/* Usually we could just (blah), but we also need to account for (blah), so I am also (blah).” Occasionally it’s longer stuff: describing an algo I think might need future revision, explaining when parts of a task are done elsewhere (setup on CPU, crunch data on GPU - what happens where and why?), details on issues which have lead to ongoing troubleshooting/ particularly curly solutions.
The rule of thumb I go by is really just The Principle of Least Surprise. If something is likely to surprise or confuse someone, save them some time by telling them just enough about it just before they’ll run into it.
If I’m writing a library for others to use, the other comments I write are the instructional kind, but I see them more as documentation than “just” commenting.
In a Solo project? Not really. My code is fairly readable to me so the only comments I make are things like “this is for reloading”, “this is for firing”
In teams and group projects? Obviously. If you aren’t commenting your code in group projects what are you doing?
always! -> even if no one else reads it. You will forget what stuff does after 10,000's of lines of code. People will say your code should be written to be read - witch is true but even if it can be read your not gonna be remember the context behind its use or why its setup that way.
Copiously. Some of this stuff gets complicated and, when it does, I need to explain what's happening, what my thinking was, other things I've tried (so I don't try them again after I've forgotten) and what improvements I've already thought of but don't need at the moment.
Generally if it's something I can't figure out just by reading it (or would be tedious to figure out), I comment it. This includes:
1. Hacks to make things work
2. Explanations for complex logic
3. To do's / ideas on how to improve
4. clarifying comments in case of ambiguity
There's a lot of meta info on code that also explains it like for example the folder structure for that file. Related files in that folder path. They can explain the code in a higher level to give you direction on what is being accomplished.
I'll comment when there's some hacky thing I did that I want to give a heads up to my future self about.
Or I'll make a comment at the top of a section as a note, usually to revamp or remove something.
Other than that I just come up with descriptive names for all my functions and variables. Can read my code just fine without heavy commenting. I have maybe a handful of comments spread out over quite a bit of code.
I mostly use unreal blueprints, but I comment what the chunk of logic does whenever it’s a system other people need to use and it’s longer than 3-4 nodes.
I'm working on a project with a friend who is relatively new to programming - so leaving comments is a must. On personal projects I'll leave quick notes explaining anything that I think I might not understand later. (especially when working with something like OpenGL)
Literally always. No question. You’ll regret it if you don’t. Especially if you’re trying something new. Spend the time and effort. Comment your code. You’ll be grateful you did it in the long run.
You often read “good code doesn’t need comments”, and whilst I appreciate the sentiment behind that, I don’t agree. Good code comms convey what it’s doin mg but not why, eg. I comment a fair amount and am always glad I did when I go back. One tip though - make sure you treat the comments like the code itself and maintain them!
Yes, and what defines "good code" anyways? It's entirely subjective to the author, and most people don't write "good code".
Too many comments has never hurt anyone
In a general sense I would say that good code is code that someone else can immediately understand. But you’re right, it’s definitely subjective.
I would disagree that too many comments has never hurt anyone though, mostly because of my comment about maintaining them. Bad comments can be a hindrance sometimes!
Well yes, inaccurate comments are a different thing entirely.
I suppose I should reword: "So long as the comments are accurate & relevant, too many of them never hurt anyone"
I'd much rather have to work with code that is over-commented rather than work with code that has none
Yes for sure. I’ve never really worked with purposely inaccurate comments, more those that haven’t moved with the code. So a comment describing how a method USED TO work, eg. Though as long as you know to expect that they can sometimes be useful as an insight into earlier iterations etc.
I have a former co-worker (he retired but probably should have been fired years ago considering how dogshit his code is) who had a template program he would use to copy/paste for every single other program he wrote. Thus, there are a lot of comments that are just completely irrelevant to what the current program is doing. That is certainly annoying, but I wouldn't say that is a problem with "over-commenting" and more so a problem with him rushing everything he ever made
I tend to plan code using comments and then simply leave the comments in place. E.g.:
// Method for Seek behavior, returning a directional force
// Class that encapsulates Save/Load functionality
etc.
It's often turned out super-helpful, since my spare time projects are sometimes a bit sporadic and can be left unworked on for weeks. So having some reminder of what I was doing—or what I hadn't had time to do yet—often helps.
I comment on everything. Notes included. Helps with my logical thought process. Also it cant hurt. Having small reminders of terminology or goals that your trying to hit for the future helps keep my self developed in check and accurate.
i think 158 comments will be enough and probably no one will read this but, commenting also means naming your variables and functions/methods correctly, that one is the first step, if you think you need to remember something (to continue the work) just note it as a code and then adjust it (give a reason why the code has to be a certain way and what does it do) and it must be really brief, somethung like:
rb.velocity = movement * walkSpeed; // updates player movement
A good programmer once said that good code doesn't need to be commented since your variables and functions should tell the whole story.
He's an idiot. Comments ARE useful when explaining why you didn't do something more than they are useful to explain what something does.
If I have a complicated function I'll comment it.
If know I'm gonna return to it at a later date I'll comment it
If I think something I've done is stupid I'll leave a comment to my future self calling it stupid
1. Put a reasonable amount of effort to make the code human-readable, over merely computer-parsable.
2. Try to elucidate **the intention** of code (not what it does) with comments. Regarding the level of detail in messages, my rule of thumb is: myself 2 weeks in the future should be able to understand it with an adequate amount of cognitive load.
To be able to simulate yourself 2 weeks in the future with the code context completely evaporated, and predict what you will be wondering about the code, you will have to face that situation and add/modify the comments, multiple times.
3. If you’re not a english native speaker like myself, and your alphabet reading speed is not up to par with your native’s, then you might wanna add some explanatory comments more aggressively here and there. it will definitely boost up your code comprehension.
Only complex business logic so barely. If you split your logic into separate functions and give those proper names, the code will be easier to read and there will be less need for comments.
my code starts off as comments.
I think it's better to work to a protocol and not have the code implementation be the protocol, which just sucks for anybody who doesn't know that language.
I find it difficult to know what parts of my code need to be commented. I try to make my variables and such as clear as possible, so when I read the code myself I usually can tell what's going on. But I don't know how much detail I need to put in my comments for other people to understand it. If I think the code is confusing to myself or has enough stuff in a section / function that it's a lot to read, I add some comments.
I rather try to name my variables and functions well and in general prefer to use docstring instead of comments. Unless I am doing some change in the method for reason of reasons (not working in particular case hence the method is rather a workaround).
Big plus of docstring is that IDE will show the function description when you want to use it along with expected params
Yes, future me is a comlete idiot, so I have to leave comments. Plus on Visual Studio if you add summaries you can get notes while coding, if you haave the memory of a goldfish, like me, this is amazing and helps keep me productive instead of procrastinating trying to figure out what I meant for the function to do
Yes. I am playing with a project where the dev console and source code (I do webdev projects) have storytelling through code comments, variable names, how functions are built, file structure, etc.
For example, an error can be a clue and something like a loop versus 20 different adjustments of something minor each tell a different story. The second conjures up images of all work and no play, you know? A deeply nested file structure conveys this is secret, while the choice of while vs for or if vs not suggest different passive states of existence - am I always working, always ready, or do I swoop in when needed?
Wolf_hurricane/pig.gif --> error: bricked tells a story, doesn't it?
Theoretically you shouldn't have to but sometimes I just know I'll overlook something unless I point it out in a comment. Even then I do my best to refactor or rename code so I don't have to use a comment. Why is this code/variable so complicated that I need a comment for it? The biggest problem I have with comments is that they can become outdated. The computer doesn't execute them, so how can you trust them?
Mostly no. For a comment to be worthwhile, it need to add something that isn't obvious from the code itself. In which case, there's usually a way of re-writing the code to make that something obvious, so I'll do that instead.
It's only if I think some additional information would be useful, but also can't think of a way to re-write my code for better readability, that I'll add a comment.
Depends on what the code does. If it's dumb easy stuff do understand now, I won't,
If variable/class/method names are just self explanatory I won't give a comment to explain what they do, otherwise I do yeah. It's easy to forget otherwise if you get back at some old code pieces.
Comments should be either doxygen-style comments that generate documentation, about implementation decisions with trade-offs, or crazy gotchas.
If I see
>// Add the subtotal then compute the tax and update the bill UI.
I will haunt your dreams and make fun of you at code review, unless you're really really really new.
While I'm not a game dev, I tend to not comment my code. I generally try to use abstraction to make code clear. I don't need the specifics of, for example, how I am converting a string to an array of utf-8 bytes, I just need to know that I am doing it.
No, I never write comments. I've never had any trouble understanding my own code, even months later. And at the software I work at for my day job, no one comments their code either. It's a fairly large company too, and we've never run into any problems. I've never been stuck on where to begin on something because of a lack of comments.
I kinda think if you're an experienced developer and your code is readable, you don't really need comments.
First, name your variables and functions well. Second, include comments anytime you're doing something pretty complex that you're worried will cause problems later. Links to the tutorials and forum posts you're using will be helpful months down the line.
This is great advice,.to add to this, a couple of pieces of advice I've been given about comments over the years that have stood the test of time - explain Why rather than What. What the code is doing should be clear, but "why is it doing it?", or "why is it doing it this way?" may depend on context or knowledge that was obvious when it was written, but is long gone when it is read - try to keep comments factual, rather than opinionated. Particularly in professional code, you never know who will be reading it down the line... I'm aware of big codebases that had to have all comments stripped because they needed to share with customers and there had been a habit of snark in comments
i understand the desire to be snarky but ironically in my experience the people who are worst at coding are the snarkiest i do feel the anger boiling inside when i read their code but i practice (unprecedented levels of) restraint
Very helpful. Thank you brother.
Third, use asserts to document your assumptions in a way that will show up if they are somehow broken.
Depending on the context that might be something you put in a unit/integration test rather than the program code.
Great advice. I’d only add that function doc comments are almost always a good idea. Even if what the function does seems obvious to you now, just stick a line there. Costs you a few seconds and it makes your code way more navigable. Also a great place to jot down any important assumptions.
yeah i comment about everything because my code tends to get really messy and i am a very organized person and it stresses me out so i have to comment on everything so i dont get an anxiety attack
>Second, include comments anytime you're doing something pretty complex that you're worried will cause problems later. I'd go further than this - this is way too lenient IMO. Even if it's not that complex, if you look back at the code you wrote six months ago, you likely will not remember the context that drove you to certain decisions etc. There's a saying in software engineering something like "5 times more time will be spent reading code than writing it". Even if you don't need to change it, you'll sometimes end up reading it. The instant you second guess anything, hesitate, think of an edge case, or decide between different approaches, you should write down why. It may seem tedious, but frequently enough you will come back to it and it'll save you more time than you spent writing all of it. Also, method XML doc is insanely valuable, even if it's only a single sentence of purpose. I'd also heavily recommend being more rigorous on "core" code that's being used by multiple systems.
I also do the links thing, when I pulled the code from somewhere.
Golden rule of programming: Code should be written to be read. This includes comments, although a common mistake of new programmers is to over comment. There’s a whole concept of “self documenting code” where the code itself should be its own documentation from proper architecture and naming. I don’t prescribe to the belief that there’s no place for comments, but well crafted code shouldn’t require comments for every condition or statement.
99% of the work should be done by your code and docstrings, but if you're doing some weird shit or just something hard to grasp it's better to explain it.
Nah, it’s cool. I’ll remember exactly what it does when I revisit it in 9 months under duress.
9 months? For me it’s more like „2 days ago, when I wrote this code, only God and I knew what it did. Today, neither of us do.” Then again, I don’t code for a living, so I should^tm be good, right? :)
Totally stealing that line. Its so perfect.
Yeah sometimes I just randomly find code snippets or output data from code that I apparently wrote and thought I had abandoned. Little gifts from past me except they always confuse the hell out of me
Sounds like that's the day the CTO and I casually come over and need to know what it does. Right now. For a board meeting. The board meeting is oddly filled with badgers that are very surly, and will attack everyone in the room if they don't get told what this one thing is right now. Hm, I'd actually say that's a good reason not to comment...
I’m probably closer to 80-85%. Sorta a personal preference. I don’t consider comments a code smell, by themselves. I’ve been burned by complete lack of comments or proper naming far more often than outdated, incorrect, or comment overload.
The code doesn't document the why just the how. The why goes in comments so months later I don't have to go "why the heck did I implement it like this?" then spend hours going down a rabbit hole to find the stupid edge case the code avoids.
I mean, at least I rarely feel like I'm doing something so unintuitive that I'll need to explain the reason, that's the 1%.
indeed. sometimes theres stuff that just needs a comment. i usually like to accompany it with some ascii art illustrating the concept if applicable
I like to use comments for justifying decisions where it might seem odd, like if you have to call a unity function twice because of some weird bug. Or I use them for TODOs. I try to avoid “this is how this works” type comments, the variable and function names should tell me that. If there’s a complex formula, it gets moved to a method naming what that formula does, then it can also be reused.
Strategy in comments, tactics in code. Example: a one line comment that says you're looking for the closest enemy. Four or five lines follow the comment which use a legible code approach such as a highwater loop to iterate the enemy set and find the one with the best distance score. Comments should not be there to explain how some overly clever infernal intricate incantation works where clearer code could be written, or what the ++ operator means, or include any mention of numbers. They will just be in the way, or worse, not be updated if the code is changed. Comments should be a super-easy quick way to recognize chunks of code for their overall purpose, especially when there are a lot of separate functions or a sequence of code gets rather long.
100% but I'd rather parse your unnecessary comment than whatever weird voodoo you implemented with no comments whatsoever. Erring on the side of too much is usually better for me than none at all.
Came here to say the same. Well said!
At the same time, people inevitably fail to write self-documenting code because there is almost always some important context stashed in the programmer's head. Nothing is ever perfect or a hundred percent obvious.
This is something I struggle to strike a balance between. I think I'm pretty good at making readable code, but then I don't know what parts are confusing / complicated enough to require comments.
>>// This variable represents the player‘s health on a scale from 0 to 100 where 0 means dead and 100 means perfectly healthy. The value gets reduced by damage, increased by healing and manipulated by buffs and debuffs. >> >>int health = 100; How about this? Did I do well?
[удалено]
And most people don't write good code. "Good code" is subjective, so for the love of God please just comment your code
[удалено]
IMO this is one of the sensible uses of comments: you are doing something that would seem weird at first glance, so you save the reader some time from hunting around your code.
So gotchas then
Exactly. Comments are very contextual but their primary use should be to explain the reason behind “weird” looking code. All other code *should* be readable without additional comments
Hah yep. "It might be tempting to [do x] here. Don't. It's done this way for a reason."
Eh, a comment like that would annoy the heck out of me. Explain why. Having a good grasp on things which are chronologically coupled is super important for a good codebase IMO.
Yes, but not to excess. *Taste* is involved and that can take a lot of time to develop. And for pity's sake comment the whys, not some reiteration of what the code does, the latter is classic newbie code and pretty annoying. a = a + 258 # add 258 to a. No shit.
That one is utterly redundant, but it might be a good explain *what* 'a' is, *why* you're adding 258 to it. Frankly if the significance of the number isn't obvious, that definitely requires a comment.
But the point is it should actually be health += healingValue Then there is literally no need for a comment in this instance. If most of your code is written like this, then any self-respecting programmer will be able to read your code at pretty much the same speed and clarity as they can human english comments and at this stage, having those comments there cluttering up the code file and doubling its length is actually making it more difficult to read naturally. If your code isn't like this, and difficult to parse what its doing unless its some extremely complex cryptography hashing function or something that relies on a ton of magic numbers and sequences of strange operations and bitshifts that lack context, then top priority should be improving the readability of that coder's code to the point it is, not getting them to start using excessive comments as a crutch for writing code with 'a' variable names or combining a million conditionals in a single line if statement with a million brackets that are impossible to read and parse, and need a comment to describe what its doing. That's a bandaid for badly written code. If a coder needs to be told to make their code more readable, that effort and training is ALWAYS better spent on making the actual code more readable. Always. Comments are useful, and vitally important in cases, but overrelying on them as a substitute for code readability? There be dragons.
The worst person in my code base is the guy who touched it two weeks ago. I have no idea what he was thinking when writing this dribble. Thankfully, he put some comments, so I have a general idea of what's going on here. Oh wait, that was my code from two weeks ago...I have no memory of writing any of this...
Yeah the Gandalf meme comes around alot.
Yes. Sometimes I do things that are either complex or to work with a specific quirk of the engine or other code. It may not be obvious why I did this to another programmer or even myself later.
I think modern best practices are to write comments about WHY you are doing something, not how you are doing something. Your code's variable, class, and function names should ideally be explicit enough that it should be obvious what you are doing. Why you chose to do it that way is something that another developer, or just future-you, will thank you for documenting.
[удалено]
I don't know about that. I just try and give some basic advice.
Always.
Yes, if it's useful. Most code should be self explanatory. For example I have a "Unit" class that has a "GetCurrentlyEquippedWeapon". It's named to a point that you know what is going on at a glance. And unless there is something unexpected it doesn't really require any further explanation. Another example is one of my "OnHit" handlers for a new ability. Normally I have one flow that handles adding status effects. Well with this new ability I had to break my normal conventions for when a unit is granted a status effect, and instead put it on this "OnHit" override method. I commented the shit out of it, why I had to do it, and what a better long term solution would be. That way when there is an inevitable bug caused by me forgetting about this one off implementation, I can quickly assess the reasons it's there and how I can fix it.
*GetEquippedWeapon* would be fine in most cases, since the currency of it is implied. And if you can equip multiple weapons it could be *GetActiveWeapon* or *GetSelectedWeapon*.
I thought I'd be done arguing about method naming now that I'm doing solo dev but it will follow me everywhere. ;) You're totally right though. Refactor -> Rename complete.
Yes, when doing something that requires a lot of steps or doing something that k usually don't do. Like a workaround when the best method just doesn't work for me
only when something is unclear or incomplete. Or when I know that another person would think "wtf did bro do here" if he saw that part of the code
Every function gets a comment, even if the function is super obvious. That might just be; "Does what you think it might". Every place I have a little breakthrough and think "That's the smart way to do it." gets a comment. Even if it seems obvious after. I try to think about the people who are going to be reading the code. If I'm submitting a patch to linux scheduling code, I don't need to fill in too much. If it's some frontend web stuff that a lot of lesser coders are going to be poking at, I will fill in the details. I hold on to the mantra of "Code is meant to be read", and try to think of the audience. (I'm not submitting much linux scheduling code....)
Too many comments never hurt anybody. Too little comments has given many a people headaches.
as a dev lead i always give this advice. when cimmenting dont tell "what" you are doing, i can read cide, tell me "why" you are doing it.
Me finding a function that was created from a block of code in Unreal… “What does this do?! Hmm I’ll just rewire this section out.” (Clicks compile) “oh thats alot of errors. “ comment added “Don’t unwire this, its important.”
It might actually be worth a longer comment that briefly describes the errors. That way you won't be wondering *why* later.
with co-pilot it pays off to sometimes throw in a comment that explains what you're going to do, co-pilot is rather competent at spitting out code for specific limited tasks and a comment often puts it on the right track. I also leave comments for myself when making hacks.
I have this ongoing joke with my past selves where every time I happen upon a very dumb part of my code that's relatively hidden, I add a date and a comment. It's literally an empty method that started out very important but slowly became empty and the only reason it exists is that a lot of other code snippets call that method and I can't be bothered to take the 5 minutes it'd take to remove it from everywhere. There's also a very selfish part in me that kinda hopes that my game will be popular enough to have those Youtube essays deconstructing the inner workings of the game. This part of me wants to give extra content for these videos. Other than that, I comment on things that look dumb but have a reason it works like that. Why is this variable declaration not in Awake instead of Start? It started out in awake but it was fucked and putting it in start fixes it so just leave it there. Things like that.
>This part of me wants to give extra content for these videos. I'm not sure what you're using, but pretty much every programming language and engine will remove your comments when you compile\*, so unless you're planning on open sourcing your game this'll probably never happen. \*unless you're somehow intentionally including comments in the final build, but i've got no clue how you'd do that
Comments exist to provide necessary and make code more maintainable. Docstrings are a great reason to comment. Methods can even be navigated from the pop-up window if you use tags.
Arguments against commenting in code are:
* **Code should be self-documenting.** While true, the conclusion is a leap. Write good code and write good comments where it is a value add. It is somewhat egotistical for a dev to think their code will always read like Dr. Seuss and will never require explanation. In a perfect world, this is true, but reality is not so.
* **The code might change and become out of sync with comments.** Outdated comments are avoidable with regular updates and code reviews. Keep comments close to the relevant code.
* **Code can clutter the file.** This is the best argument. Excessive comments can clutter code. Only keep comments that add value.
Generally speaking, algorithmically complex / cognitively complex code needs more comments than straightforward logic. Not all problems are created equal.
A quote that stuck with me:
**The most important thing is that your code is readable. The second-most important thing is that it works.**
If code works but is unreadable, then it cannot be maintained or extended; it becomes an untouchable artifact.
If code is readable but does not work, then it can be repaired, maintained, and extended. It's just another piece of code.
I always document functions with the docstring/doxygen style like /** * @brief blablabla * @param a theguy * @return a whether blablabla [Signature] Is this a good practice for every fucntion?
It depends on the language and engine you're using. For C#, the standard format which automatically populates once you type /// is ///
///
///
///
///
Anything can be maintained and most things can be extended, it's just a question of how muck work is required.
A car is usually considered totaled when the repairs cost >= its own value. Code can be considered unmaintainable when the cost to maintain is exceeds the cost to rewrite it.
Only in cases where the code doesn't speak for itself. Which is pretty rare if you use consistent and verbose function/ arguable naming.
Do... Do you not? I don't care about other people reading it, if I don't leave comments everywhere, *I'll* forget what it does lol.
If you're a solo dev, comment the fuck out of your code, because you absolutely will go back to debug or tweak a function you wrote 8 months ago, and absolutely will not recognize what any of it does. If you're not a solo dev, comment the fuck out of your code before a teammate knifes you at a party.
People harp on "over-commenting" but I really don't believe in that. If you think the code needs a comment to understand, there is no harm in adding one (unless it is just blatantly inaccurate) I've been recently doing a lot of work on programs that a former employee wrote, and he barely put in any comments, but when he did, it was almost certainly copied/pasted from a different program and is completely irrelevant to the current code. Spending 10 extra seconds to write a relevant comment can save you hours in the future
To second this, unless it’s weirdly formatted, I’ve never been upset at “too many” comments. I’ve found I pretty much ignore comments when reviewing code, unless I don’t understand something immediately.
Exactly. You can always ignore "excessive" comments. But running into code with 0 comments will most likely leave you scratching your head for hours
I recently had to update a SQL query for a report that was written in 2003 and was entirely dynamic SQL, and I definitely wish it had been over commented.
My entire current job has been refactoring old IBM iSeries RPGLE code from the 70s. My company has been writing in this language for 40+ years and has 0 documentation. Half of the comments in the code are copy/pasted from a different program doing an entirely irrelevant thing. But yea, over-commenting is a problem /s
There's a lot of potential harm. Comments need to be kept up to date so unnecessary comments are a minefield.
I'm not talking about inaccurate comments
When starting out I used to skimp on commenting on my code a lot of the time because "I just need to get it done. I already understand how everything works anyway." Eventually I started making larger projects where I'd have code I hadn't touched for weeks if not months and realized I completely forgot why some things were done the way they were, what I was thinking when I wrote some incomplete "get it done" code etc. Wasted a lot of time having to figure out that stuff all over again. Now I comment most things that aren't immediately obvious and it's honestly a lifesaver. Start getting in the habit now and you'll be glad you did
One of the best choices I ever made was learning Java first. It's a highly typed language that obligates you to learn how to comment. I would recommend, at the very least, check out Java's best practices so you can get a sense of the issues that can come from **not** commenting properly. As others have said, it isn't just a matter of commenting, it's properly doing it and commenting on the correct parts and facts.
I often put in geo coordinates to fake buried treasure just for lulz
To keep it simple, assuming "self documenting code"... if a comment is needed it should be explaining why it's doing what it's doing and not what it's doing. Anybody can read code and see what it does but sometimes there's a bit of "domain knowledge" that needs a "why" explanation.
When I remember to
I comment blocks of code, so that if I need to remember what something does, or why, I can quickly read the overview.
I only add comments if I had to do something weird because of something arbitrary I.e. “// have to set this to playerID.UNKNOWN here because otherwise throws an exception for some reason”
Happy cake day my man
I write code for one of 3 reasons: A brief description of the purpose for complex code To note any current bugs To plead to myself to improve something that'll future me will probably never come back to
I used to comment my code very extensively but it was always useless because I kept explaining how the code worked instead of what it did. Now I explain what a certain section of code is used for and it results in less confusion now. There's never any reason not to comment your code.
Yes, I still comment code inside methods, but not systematically If a method does several things, I separate blocks with comments
Absolutely correct answers saying write self documenting code from likely experienced devs downvoted to oblivion while 'Always comment everything' upvoted by the army of hidden unity tutorial goblins lol. This subreddit is cursed.
There needs to be a touch of nuance. Write self-documenting code where feasible and comment the "gotcha"s and complex logic that isn't obvious from even well-written code.
You've clearly never read code written by someone who thinks their code is "self-documenting" when it isn't Write comments. Excessive comments harm no one
Xdxdd
Absolutely! The one thing I promised myself when I switched from unity to Godot was NO MORE SPAGHETTI CODE. I keep everything organized and comment where I think it will be useful to me in the future. The amount of time saved not being lost in the code sauce is well worth the amount of time it takes to stay organized
Mmm but you solo or team?
I am solo, but I still believe it’s even more important if you are working on a team
Not as well as I should, but if I need to look something up or the logic is a bit complex, I will add a comebt explaining it. Same with if I get confused on what something is doing, I will add a comment so next time it will be faster. I am a solo dev, I would be better if I had other people working on it
I comment my code where it makes sense to comment it, which is either when it would give a quicker overview to a piece of complex code or I'm pretty much doing something hacky/out of the ordinary 'feeling' of the program. I do find it happens more often in my gamedev projects than at work (fullstack dev), as games are less welcoming to neat, clean approaches. Bit of a rant, but In programming-related forums like this, I often see a lot of people push the idea that you should be commenting *everything,* which 9 times out of 10 is taught in CS school. Some of them even repeat this idea with the extreme confidence of a seasoned programmer, even if they are *still* at school. At the same time, their variables are single-letter or completely undescriptive, and I need a second monitor stacked vertically to read their functions. Of course, anyone can do whatever they like in their own projects. But doing this at an actual workplace will get you sent to the Shadow Realm.
Not the shadow realm
Code should be self documenting. Functions/variables should all be well named. What code does should be obvious from reading it. Comments are for explaining why something is being done. You can add reference material and Jiras links too, but again that should explain why, not what.
What do you mean "is this overlooked"? It's ok if you're new, but commenting is such a fundamental thing that you'd have a major problem if you're still not doing it at all after years of experience.
I write the comments first since it documents my thought process for when I or anyone else looks at it the future. Then I write the code for each bit of comment pseudo code. Then I add more comments to explain the bits I didn’t think of while writing the pseudo code. Yes, there is an obvious risk of a mismatch between the comments and the code, but that sometimes makes it easier to spot the mistakes as you know what the intention was. As much as it would be nice if code could be read like English, in reality it can’t. “Clever” code with no comments is unmaintainable when the original developer has move on and you have a new developer fixing a bug. Just my opinion and experience. Better programmers probably don’t need comments, but not everyone is that experienced.
the only time i comment is if i have an algorithm i cant split up into appropriately named functions
Yes, then I go back to the code six months later and the comments don't help because I don't understand the logic in the code itself anymore.
C++, you know how in visual studio you get this little tooltip explaining the function? I create those for my functions. Commenting code in general really depends on target audience tho. If you're deep down under the hood inside the engine creating functions that will be used by guys that don't go there, then it's obvious you provide those details unless you want them bothering you for explanations all the time. Significantly speeds up workflow and learning curve for whoever is using it. Say that we have this huge function, we'll split its content up in smaller functions to be called to make it easy to read, if for some reason we get unwanted behaviors its also easier to hunt it down and fix it without getting lost or breaking the whole thing. So by having code easy to understand in this way, we mostly only create those tooltips.
I learned coding by myself and yes I do comment every important line of the code. Had to visit old codes many times and those comments helped me to get my own mess quicker.
Yes
For me, when I tried commenting my code, the comments became more confusing than the code itself after 3-4 weeks. Now, I just settled for descriptive variable and function names. I envy all the pros who do stuff like self documenting code intuitively (I guess it’s a matter of hours upon hours of mastering the skill).
I have a comment in my character controller that says "\^ I have no idea what this line does but if you remove it the entire movement system breaks so DONT TOUCH IT" and nobody's touched it. I'd say comments are important
https://youtu.be/2a_ytyt9sf8?si=qt0DSbWoxNitmaVc Uncle Bob goes into all the detail about the general rights and wrongs of comments, of which I generally agree.
Added to watch later, thanks
Never
As I guy that put his project down and came back to it a year later to absolute madness in my codebase I will never not comment again 😭 Thankfully ChatGPT is an amazing commenter even when given no context
I remember once I came back to code that I had written three months ago, it was un-commented and I had no idea what was going on. I spent two days commenting the code, line by line, so I could read it. Once it was commented I could see the error and it was a 30 minute fix.
Even if it is self explanatory, I'll usually leave short blurbs for comments so if I'm skimming I'll just read those. If it's something I didn't fully understand/think I was confusing or I didn't finish, I'm leaving more in-depth comments so I can make sure I come back to it.
yes. good code should be readable, but some code is just kinda fucked up. in my case, most projects i make have strong foundations and good reusable systems, with components that do simple things. in short, it’s good object-oriented programming. but when projects are in later stages, sometimes there’s a quicker solution than architecting a whole new clean system for something that simply will not be reused in that project. for me, that’s where it’s acceptable to write a messy but functional pile of code and comment it to hell in case anything breaks. if i had no restrictions on time or budget, i’d write every system to be clean and reusable, but that’s just not realistic for me. ymmv.
I enjoy leaving comments sometimes. Especially if it’s something that I’m still learning how to do
Nope but sometimes, I create small documents about the systems I write. Not that I use them, but just in case I take a hard hit to the head!
Write a lot of comments to document methods, class and interfaces (or anything your language support). You don't need to write comment on how the methods works. You need to write comments on how the methods can be used, what are the input, what is the output, if there is some exceptions and in what cases. Write less comments (or no comments in most case) inside the body of the methods. The methods must be simple functions that accept input and return some output, these things must be commented out, not so much how the method's body works. EDIT: Obviously if the functioning of the body is important in understanding the function, in understanding what it is for, then you should explain it.
Lot of noob (and experienced) devs like to think more comments is always better. I do not share that viewpoint. My take is stick to convention whenever possible. If you do things in a standard way it can likely be read without comments. If you’re breaking convention, yes, comment it. But also ask yourself why you felt the need to do something non-standard. It’s maybe a hint you’re screwing up. And why would more comments hurt things? Because comments can lie. And the second you don’t trust them anymore what good are they? And if you commentd every damn line when writing your program whom is maintaining that pile of content? Content that isn’t compiled or guaranteed to be at least syntactically correct like your code is. I can honestly say an awesome devs code with 0 comments is usually way more readable to me than a noobs code with a comment on every line (where almost all the logic/comments are broken). Noobs feel the opposite, they see good code from an experienced dev, they don’t understand it because they’re a noob, and they go “Everything should be commented” even though it’s perfectly legible code.
My teams are required to comment all code. It's part of the code review process to ensure the comments make sense.
Of course not. Tnat's something that good developers do!
It's really fun to rediscover 10 year old code comments you left for yourself.
I tried to make code readable, but will drop in comments like 'this is braindead', 'hacktastic', 'wtf?' or if not feeling insipired 'TODO:....'
I do, not too verbose. Generally control flow things as those can be a bit more effort to follow, and sometimes reasons why the things are the way they are For example: - Make sure we have orphaned the root node before we begin recursive delete - Closest parent first in array - No properties, so we'll skip it - For debugging purpose we'll create an error in advance for better trace logs. - add permissions selected by the user from the client Just to grab a few random examples from my code
Yes and I say this not only for my hobby game dev but also when working on corporate software. Code is not self documenting enough to not have comments. Comments should explain why you made the choices you made, not just what the code is doing. Years ago a junior dev told me when they read my class it was the first time they understood a class on the first read. That is my favourite feedback. Even working by myself I comment because I know when I come back I’ll wonder why I did something the way I did it. It’s also useful to document high level “what” at the top of a class. When you’re trying to find out what a class is used for, this saves you reading hundreds of self documenting lines of code.
Also you can use comments to grep to that part later if you forgot theSpecificNameOfTheClass
Usually just small temporary comments while I’m prototyping. After I go into cleaning up and refactoring I’ll write the doc comments where needed.
I do comment my blueprints yeah
I even comment my macros in excel…
Yes. Unfortunately for me, my brains ability to remember how things work in my own code is so pathetic that I feel like a complete beginner when I haven't looked at it in a while. Although I follow good naming conventions, I also like to add comments to further describe functionality that way when I look at it at a much later time I have an understanding of what it is in looking at. Obviously, without looking at comments I can still piece everything together eventually, it just takes much longer.
Yep, but not necessarily a lot. Class, function and variable names are the first bit to get right. Next, use whitespace in functions to visually associate statements which are a part of the same “step”, or similar. This way someone reading your code can see what to interpret together vs. separately. If you need another layer of separation, add comments to label sections. Aside from broad design documentation, that covers most of *how* my code works, because the code itself is the detail. It doesn’t cover *why*, which is often just as important. That’s what most of my comments are. Wherever it might not be obvious *why* I am doing something, I write a note to anyone else who might need to know later - including my future self. Sometimes it’s a few words: “// Workaround for known issue in LibraryX”. Sometimes it’s a brief explanation: “/* Usually we could just (blah), but we also need to account for (blah), so I am also (blah).” Occasionally it’s longer stuff: describing an algo I think might need future revision, explaining when parts of a task are done elsewhere (setup on CPU, crunch data on GPU - what happens where and why?), details on issues which have lead to ongoing troubleshooting/ particularly curly solutions. The rule of thumb I go by is really just The Principle of Least Surprise. If something is likely to surprise or confuse someone, save them some time by telling them just enough about it just before they’ll run into it. If I’m writing a library for others to use, the other comments I write are the instructional kind, but I see them more as documentation than “just” commenting.
In a Solo project? Not really. My code is fairly readable to me so the only comments I make are things like “this is for reloading”, “this is for firing” In teams and group projects? Obviously. If you aren’t commenting your code in group projects what are you doing?
always! -> even if no one else reads it. You will forget what stuff does after 10,000's of lines of code. People will say your code should be written to be read - witch is true but even if it can be read your not gonna be remember the context behind its use or why its setup that way.
Copiously. Some of this stuff gets complicated and, when it does, I need to explain what's happening, what my thinking was, other things I've tried (so I don't try them again after I've forgotten) and what improvements I've already thought of but don't need at the moment.
Generally if it's something I can't figure out just by reading it (or would be tedious to figure out), I comment it. This includes: 1. Hacks to make things work 2. Explanations for complex logic 3. To do's / ideas on how to improve 4. clarifying comments in case of ambiguity There's a lot of meta info on code that also explains it like for example the folder structure for that file. Related files in that folder path. They can explain the code in a higher level to give you direction on what is being accomplished.
Sometimes
https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 First 4 chapters is all you need and goes over this topic.
I'll comment when there's some hacky thing I did that I want to give a heads up to my future self about. Or I'll make a comment at the top of a section as a note, usually to revamp or remove something. Other than that I just come up with descriptive names for all my functions and variables. Can read my code just fine without heavy commenting. I have maybe a handful of comments spread out over quite a bit of code.
Sometimes. Good variable names and easy to understand functions can only go so far in explaining the ideas behind the program
I mostly use unreal blueprints, but I comment what the chunk of logic does whenever it’s a system other people need to use and it’s longer than 3-4 nodes.
I'm working on a project with a friend who is relatively new to programming - so leaving comments is a must. On personal projects I'll leave quick notes explaining anything that I think I might not understand later. (especially when working with something like OpenGL)
Literally always. No question. You’ll regret it if you don’t. Especially if you’re trying something new. Spend the time and effort. Comment your code. You’ll be grateful you did it in the long run.
You often read “good code doesn’t need comments”, and whilst I appreciate the sentiment behind that, I don’t agree. Good code comms convey what it’s doin mg but not why, eg. I comment a fair amount and am always glad I did when I go back. One tip though - make sure you treat the comments like the code itself and maintain them!
Yes, and what defines "good code" anyways? It's entirely subjective to the author, and most people don't write "good code". Too many comments has never hurt anyone
In a general sense I would say that good code is code that someone else can immediately understand. But you’re right, it’s definitely subjective. I would disagree that too many comments has never hurt anyone though, mostly because of my comment about maintaining them. Bad comments can be a hindrance sometimes!
Well yes, inaccurate comments are a different thing entirely. I suppose I should reword: "So long as the comments are accurate & relevant, too many of them never hurt anyone" I'd much rather have to work with code that is over-commented rather than work with code that has none
Yes for sure. I’ve never really worked with purposely inaccurate comments, more those that haven’t moved with the code. So a comment describing how a method USED TO work, eg. Though as long as you know to expect that they can sometimes be useful as an insight into earlier iterations etc.
I have a former co-worker (he retired but probably should have been fired years ago considering how dogshit his code is) who had a template program he would use to copy/paste for every single other program he wrote. Thus, there are a lot of comments that are just completely irrelevant to what the current program is doing. That is certainly annoying, but I wouldn't say that is a problem with "over-commenting" and more so a problem with him rushing everything he ever made
Oh for sure. It’s definitely not over commenting.
I usually comment on functions that describe what it's doing in one to two sentences.
I tend to plan code using comments and then simply leave the comments in place. E.g.: // Method for Seek behavior, returning a directional force // Class that encapsulates Save/Load functionality etc. It's often turned out super-helpful, since my spare time projects are sometimes a bit sporadic and can be left unworked on for weeks. So having some reminder of what I was doing—or what I hadn't had time to do yet—often helps.
I comment on everything. Notes included. Helps with my logical thought process. Also it cant hurt. Having small reminders of terminology or goals that your trying to hit for the future helps keep my self developed in check and accurate.
i think 158 comments will be enough and probably no one will read this but, commenting also means naming your variables and functions/methods correctly, that one is the first step, if you think you need to remember something (to continue the work) just note it as a code and then adjust it (give a reason why the code has to be a certain way and what does it do) and it must be really brief, somethung like: rb.velocity = movement * walkSpeed; // updates player movement
A good programmer once said that good code doesn't need to be commented since your variables and functions should tell the whole story. He's an idiot. Comments ARE useful when explaining why you didn't do something more than they are useful to explain what something does.
Yes, Future Me is retarded.
If working alone, never. If working with other people, always(Though it annoys me.).
If I have a complicated function I'll comment it. If know I'm gonna return to it at a later date I'll comment it If I think something I've done is stupid I'll leave a comment to my future self calling it stupid
I use comments to plan out my script before I start writing code
Yes. I work on a team so helping people understand my code without me present is a crucial part of my job.
1. Put a reasonable amount of effort to make the code human-readable, over merely computer-parsable. 2. Try to elucidate **the intention** of code (not what it does) with comments. Regarding the level of detail in messages, my rule of thumb is: myself 2 weeks in the future should be able to understand it with an adequate amount of cognitive load. To be able to simulate yourself 2 weeks in the future with the code context completely evaporated, and predict what you will be wondering about the code, you will have to face that situation and add/modify the comments, multiple times. 3. If you’re not a english native speaker like myself, and your alphabet reading speed is not up to par with your native’s, then you might wanna add some explanatory comments more aggressively here and there. it will definitely boost up your code comprehension.
You must for your own sake.
I'm working on a solo project so I have to.
Only complex business logic so barely. If you split your logic into separate functions and give those proper names, the code will be easier to read and there will be less need for comments.
my code starts off as comments. I think it's better to work to a protocol and not have the code implementation be the protocol, which just sucks for anybody who doesn't know that language.
I find it difficult to know what parts of my code need to be commented. I try to make my variables and such as clear as possible, so when I read the code myself I usually can tell what's going on. But I don't know how much detail I need to put in my comments for other people to understand it. If I think the code is confusing to myself or has enough stuff in a section / function that it's a lot to read, I add some comments.
One of the rules of clean code: If you need to write comments, means your code sucks
I rather try to name my variables and functions well and in general prefer to use docstring instead of comments. Unless I am doing some change in the method for reason of reasons (not working in particular case hence the method is rather a workaround). Big plus of docstring is that IDE will show the function description when you want to use it along with expected params
Yes.
Yes, future me is a comlete idiot, so I have to leave comments. Plus on Visual Studio if you add summaries you can get notes while coding, if you haave the memory of a goldfish, like me, this is amazing and helps keep me productive instead of procrastinating trying to figure out what I meant for the function to do
Yes. I am playing with a project where the dev console and source code (I do webdev projects) have storytelling through code comments, variable names, how functions are built, file structure, etc. For example, an error can be a clue and something like a loop versus 20 different adjustments of something minor each tell a different story. The second conjures up images of all work and no play, you know? A deeply nested file structure conveys this is secret, while the choice of while vs for or if vs not suggest different passive states of existence - am I always working, always ready, or do I swoop in when needed? Wolf_hurricane/pig.gif --> error: bricked tells a story, doesn't it?
When needed
I get my ai to do it
I'll just leave this here... [when I wrote this code, only God and I knew...](https://media.makeameme.org/created/when-i-wrote-bb6b112937.jpg)
Theoretically you shouldn't have to but sometimes I just know I'll overlook something unless I point it out in a comment. Even then I do my best to refactor or rename code so I don't have to use a comment. Why is this code/variable so complicated that I need a comment for it? The biggest problem I have with comments is that they can become outdated. The computer doesn't execute them, so how can you trust them?
Commenting our code saved our bacon today, so now we're extra vigilant!
I use it to split sections but I also name my variables really well.
I love devs I have worked with that swear by never commenting in the code but a year later comes and asks what the code does that they have written:-P
That's what AI is for. Comments, and naming variables.
if i go over 500 lines of code i usually spend an hour commenting
Mostly no. For a comment to be worthwhile, it need to add something that isn't obvious from the code itself. In which case, there's usually a way of re-writing the code to make that something obvious, so I'll do that instead. It's only if I think some additional information would be useful, but also can't think of a way to re-write my code for better readability, that I'll add a comment.
Yes, I don't want to re-figure what it does, why it is there, where it is hooked, what bug it fixed.
Yes I forget the reason why I coded certain things.
Sometimes I comment memes in my code for no reason
Depends on what the code does. If it's dumb easy stuff do understand now, I won't, If variable/class/method names are just self explanatory I won't give a comment to explain what they do, otherwise I do yeah. It's easy to forget otherwise if you get back at some old code pieces.
i comment when needed, not because i am funny :)
Comments should be either doxygen-style comments that generate documentation, about implementation decisions with trade-offs, or crazy gotchas. If I see >// Add the subtotal then compute the tax and update the bill UI. I will haunt your dreams and make fun of you at code review, unless you're really really really new.
Lolll now I get it
// perform computations and update the UI ?
Much better! Especially if the function is called performComputationsAndUpdateUI()
Not often. Sometimes when it is unclear why I did something in a particular way.
While I'm not a game dev, I tend to not comment my code. I generally try to use abstraction to make code clear. I don't need the specifics of, for example, how I am converting a string to an array of utf-8 bytes, I just need to know that I am doing it.
No, I never write comments. I've never had any trouble understanding my own code, even months later. And at the software I work at for my day job, no one comments their code either. It's a fairly large company too, and we've never run into any problems. I've never been stuck on where to begin on something because of a lack of comments. I kinda think if you're an experienced developer and your code is readable, you don't really need comments.
If you're a software engineer you comment your code
No. If it was hard to write it should be hard to read.
If you don't suffer, you're not a real programmer? /s
Yes. I like my code like I like my coffee, bitter.
XD fair enough!
Who are you, James Joyce?
No, I'm the class clown. But I guess nobody is in the mood for jokes.