I forget I even wrote the stuff. Someone will ask me a question and tell me I wrote it, and I don’t believe them. Even after I check the commit history and see I did in fact write it, I have no memory of it. I’m slightly bothered by how often this happens.
dementia gaming
Why was this written like this? It makes no sense. I’ll git blame it and ask them what’s going on. Oh it’s me…
There’s no question I wrote the couple of things I’ve done for work to automate things, but I swear every time I have to revisit the code after a long while it’s all new again, often wondering what the hell was I thinking. I like to tell myself that since I’m improving the code each time I review it, each new change must be better overall code. Ha. But it works…
I stated programming games on a school computer in the early to mid 80’s. When the tape drive broke, I still used to have the code in my head, just type it all in for others to play. Now I find code I wrote last month and can’t remember doing it. At least it tends to be, “which genius wrote this” these day. Tend to leave comments everywhere for myself now, including my own name and other messages to myself like,“don’t touch this it works, your bug will be in…”
Yeah, I’m about the same age and started noticing my ability to keep everything in memory falling at around the mid 20s. I mean, I’m still probably way better at keeping all manner of obscure details in memory compared to the average person (we exercise that so much in this profession it’s only normal), but it’s below the peak point, not enormously so but it’s kind like having once been a top “athlete”, years later you know you can’t reach that peak performance anymore.
Also once you go through the full life-cycle of enough of your projects (that got shipped and a year or two later you have to pick it up and change it), you kinda figure out that even at peak “performance” you wouldn’t be remembering much from a project from years ago and start adding comments to help you pick it back up and alert you to possible pitfalls you noticed and avoided but forgot all about in the meanwhile.
Fortunally I figured it out long ago that I’ve created a couple of principles around commenting that have repeatedly saved my ass years later: things like documention parameter assumptions in functions, actually writting down the “why we do this” or commenting before the code of especially complex algorithms (I actually design the algorithm to the comment first and only after than code it).
I started a practice with my team on our wiki. We have a section named the Oamonomicon, since out system is named OAM. Any sort of weird one off request or problem gets documented there. What were the symptoms? What steps did we use to find the problem? Then if we start seeing a pattern of issues, we have a better idea of how to resolve them.
Yes, very similar practices here.
@ProfessorPuzzleCode @Aceticon
Oh ruck. At twenty I could remember the direct way through the Zac Mc.Kracken Mazes. And all the chords of our Bands songs. And all the Beatles lyrics. But heck… no code… now I at least remember the bash scripts…
Depression causes memory loss
That explains a lot… :(
“Who wrote this shit ?”
Spends 10 angry minutes in P4 timelapse
“Oh…”Gandalf: I have no memory of this place…
Maybe I just haven’t worked at a company long enough for this to happen, but I tend to remember what I previously worked on very well. I am still disgusted by the code I wrote sometimes. But that just means I’m learning and getting better at coding.
When I was a team lead, I was juggling 4 things every day.
Meetings, help a junior, PR a critical system, code a thing.
Repeat every day and after a month, I wouldn’t remember what I worked on the prior month.
Yeah, I guess that’s fair. I was a team lead for only like 2 weeks before my project was canceled, and yeah, I remember it being similar. I’m not sure I wrote a single line of code during those 2 weeks, though. I was too busy. Or maybe I did and I don’t remember, but since the project was canceled, it never came back to haunt me.
Never git blame. 9 times out of 10, pretty sure it was me and I forgot
deleted by creator
sweats in Gitlens plugin
Me too. But the other day, a junior developer and I were looking at some fairly old code, and I recognized the writing style in the comment as mine. We ran
p4 annotateand, sure enough, I was the baddie.
I had so many arguments with my team lead. He thought comments were an antipattern because that meant the code wasn’t expressive enough.
I understood where he was coming from, but a little hint here and there why the fuck the code is doing what it’s doing would’ve been nice.
Yeah, good code should explain the “what” without the need for comments. Good comments explain the “why”.
Generally, you can replace some comments with variable names or comment names. Which means you must already be in the habbit of extracting methods, setting new variables to use appropriate names, and limit context to reduce the name (Smaller classes and methods means shorter names can be just as expressive, because the context is clearer). It lowers the number of wtfs per minute you get reading code before you even need whole sentences to explain why things are done in a certain way, because the names can be a powerful hint.
But realistically, you end up needing comments for some things anyways.
You sound like an awesome co-worker. I love the way this is stated, and I’m 💯 in alignment
Also some parts of code are just going to smell, because of deadlines, other trade offs. For those it helps to have a comment to really highlight that bit of weirdness - the what and the why. If it is weird it should really “pop out” when you’re reading it.
It’s a bit more complex than that.
On one side you should put comments on the choices of how to do certain things at a code level that are the product of external limitations or requirements (over the years I’ve seen quite a lot of code which was kept doing things in a certain way and turned out the actual reason for it had long stopped being applicable) whilst most of the code should indeed be done to be self explanatory (though complex algorithms, especially if optimized or relying on obscure functionality, should probably be preceeded by a summary).
However, go up one level to software design and suddenly comments become more important (at the function and class level). They document functionality for significant chunks of code (so make it way faster for people trying to figure out the design of a code base they never saw before, as otherwise they would need to wade through a lot of code) as well as implied expectations in things like parameters or return values (i.e. that a variable is never expected to be null, that a zero size string is treated as NO DATA and so on) of functionality meant to be called from the outside (a kind of comment which is really just a lightweight form of an Interface Requirements Specification document). Mind you, over the years I’ve seen tons of comments documenting functions “just because” and without understanding what’s the point of doing it (probably because the programmers were told the HAD to do it) in the libraries and frameworks from some of the biggest companies around.
You could say the WHY of commenting is also important.
Yes, two of the most important things I see comments do is explain things like boundary conditions, “This is why we stop at 50 here.” and historical reasons “We have to return a 1 here because we still use calling func FOO for all of our calls still and it expects 1 as the default…”
Another helpful use is to describe the expected format of the input. “We expect a struct with this format here…” Stick in a small example too. It makes it so much easier to quickly scan the code’s flow.
Often you can find the “why” in the file’s Git history. If done properly, you should be able to find which commit introduced this change, and which issue is attached to this commit.
I used to work with a guy who insisted his code was self explanatory, and then he’d nest loops 5 levels deep and give variables names like “thingyOne”.
“thingyOne” is self explanatory, it’s a thingy.
Namely, the first one. Next you’re going to ask about thingySixtyNine or thingyOneHundredTwentyTwo, I suppose?
I don’t know why you guys are so dense. How pedantic do thingiesNumX need to be?! It’s perfectly obvious!
When people don’t understand WTF you’re talking about, it’s just cause they’re dumb. Communication is for the weak.
- Confucius
And turn signals are giving information to the enemy
Could be worse, it could’ve been customer_ID, Customer_id, customer_Id…
I wonder if there’s a warning for that in Clang or GCC. That seems like something I’d want, but also want it to be 100% opt-in. Not even enabled with
-Wallor-Wextra.
I worked with a guy who was smart but “useless smart”. He was convinced that “code is self descriptive”, that is comments are not needed because the code speaks for itself. Well that is like saying DNA is self descriptive. Yes, I can sit there tracing the code, tracking the variables, etc or you could make a small effort to describe what is happening instead and save me a lot of time and risk missing subtle points.
deleted by creator
I had a boss who hated comments because he wanted “clean code,” and that comments means you aren’t using the wiki. The build approval process actually stripped out all comments via a script.
Then we lost the wiki.
The build approval process actually stripped out all comments via a script.
Thanks, Satan.
I’d watch the movie.
For my own amusement I’m going to pretend you were using something like Perl where determining what’s a comment and what’s code can be context sensitive.
i.e. stripping from
#to the end of the line can be a very wrong thing to do in a language where the comment marker can actually be used in other niche ways.Strip the wrong “comment” and your code won’t compile. Or worse, do something unexpected.
It was all python, ruby, bash, and ansible
deleted by creator
It kind of feels like engineers look for simple solutions to what are ultimately complicated psychological questions sometimes.
I agree with your team lead wholeheartedly, but not for the reasons he would tell you. Comments should be used when code is too complex for the “name your variables nouns and your methods verbs” convention doesn’t communicate what the code does in a narrative fashion. Thing is, that level of complexity is definitely a code smell. You seem to be saying that clarifying comments are the solution, he seems to think that you should be able to rename vars and methods until the meaning is clear, and Im offering a third way: figure out why the fuck the code is doing something hard to understand and maybe try to unfuck it, then resort to comments if and only if that’s not possible. Remember that a code smell isn’t necessarily something that needs to be removed, it’s just a flag that says “let’s make double damn sure there isn’t a better way to do this before we do it this way”.
Yes, you don’t need to comment “n++” to say it is incrementing it but you should mention why you are starting with 1 instead of 0, etc. Boundary conditions are notoriously tricky and need to be documented. Then there are historical reasons that are NEVER obvious, “This function has to return -2 as a default because we’ve been calling it using X for years and it expects a -1 as the error…”
this function returns -2 as success and -1 as error
Thats exactly the kind of thing I’m talking about when I say to prioritize refactoring over comments. If you own the system returning the error code, drag it out of the 1970s and have it return an error object with some actual information in it instead. If you don’t own the system, wrap the error code in an enum that adds syntactic meaning or do a map of integer and exception and then return the mapped exception. The very last resort, after you’ve tried everything else, should be
return -1; //-1 indicates successI’ve worked on satellite command and control software that is literally using a 1970s OS. The code is limited for historical reasons and you have to work with the structure you are given.
okay. doesn’t mean you still shouldn’t refactor or add a layer of abstraction where you can. we’re looking for a generalizable principle here and generalizable principles don’t assume that you’re working with satellites that are older than the dev.
deleted by creator
Let me Guess, There is no added value in comments. Customer dont want to pay for comments, only for code that adds value.
Sometimes I just leave “feed it back to ChatGPT and ask to explain” sort of things xD.
This might not sound logical, but when you are writing Ansible for something that has no module or very complex - mix of Jinja2 templates and yaml tasks makes it superb hard, especially if you are looking for the first time.
Seriously, comments are useful, especially in top of the function.
My favorite part is looking at my ancient code and thinking “Holy hell I don’t remember being that smart. What happened?”
Everyone knows that debugging is twice as hard as writing a program in the first place. So if you’re as clever as you can be when you write it, how will you ever debug it?
Brian Kernighan - The Elements of Programming Style, 2nd edition, chapter 2
A similar phenomenon is knowing you’re going to need to go back and update some older section of code and when you finally get around to it, it turns out you wrote it that way to begin with. It’s like… I didn’t think I knew about this approach before…
“I’m dumber but wiser” - me, hopefully
This right here. Plus stuff like “this is the functions section” and “this is the main script” helps make shell scripts more readable because functions have to come first, and if you just want to get to the main point, you can skip the functions section.
I am working with an in-house “rapid development team.” They have rigorous intake, story and task break down, scheduling of sprints, QA, definition of done, integration test coverage, E2E and min 90% unit test coverage etc. etc.
They have a strict policy of “no code comments, self documenting code only.” They will go in and remove comments that my DevOps team puts in there, because it screws up that policy.
Luckily, we adopted the policy of having local branches with these comments in place. Once they move beyond the project, we’re putting them in.
The vitriol the “Clean Code” cult has against comments is unbelievable…
too many lines!!!
They do have a point though. When we’ve gone through phases where the industry focuses on commenting code and other documentation, most of it is useless.
Code comments should have a reason, and are no substitute for readable code.
However you’re also right though that people jump onto “all or nothing”. I recently did a code Review that I held up for comments. In this case, they were doing something very atypical to get around a limitation so it was a clear case of comments needed. The next person through will say “what is this shit?” And “fix” it, without knowing there was a good reason
Yeah “why” comments are absolutely fine, “what” comments are useless at best and can be harmful at worst.
I feel like this constant flood of “write comments” posts are from CS students who are told to comment everything by their lecturers. Descriptive variable and function names help explain the “what” of code pretty well most of the time.
Sure with some old languages like C89 where you are limited in your variable name length you probably do need comments to explain wtf is going on, but most code bases aren’t as constrained.
I have this argument with other devs all the time.
Hey, you know this 200 line nested if statement that suddenly returns in the middle of the condition is “7”? Yeah, that needs a refactor or at least a fucking comment.
I get a pull request that adds a log line that reads something like “special case 7 triggered.”.
Plot twist: it was a 7 Boom game.
Having no comments doesn’t force code to be self-documenting. I understand the cult of code extremist, but No-Commenters are just WEAK and PATHETIC wannabes trying to immitate the true, functional extremists, such as the 16-Space-Tabbers
That’s silly. I’ve never seen comments even as a way to explain what your code is doing (the code often does do that anyway). It’s important to say WHY you’re doing it the way you are.
That way anyone else who comes in there can have the same context you did when you implemented it, which imo is where most bugs occur. People don’t realize what assumptions you made when it was first written, and then make their own (which can easily clash).
for i in array_sometimes_we_get_ints_from_upstream_functions_and_need_to_convert_them_to_floats_or_downstream_functions_throw_exceptions: out_array.append(float(i)
I like you.
What’s fun is that this is C#, so no limit to the length of function names.
I just love it when people who have no understanding of the purposes, objectives and applicability of various parts of a famous software development process and just follow it in a blind fashion-following way.
And by “love it” I mean “get frustrated to no end even though by now I should know better”.
What sort of dev anarchy is this
I’d like all files to have a big comment on top that says wtf this is, why is it, and roughly how it works. Bonus for ascii art.
When the the documentation is epic, but no one remembers to add why this repo even exists.
I think the images are inverted
It’s a safe bet that anybody trying that jump over it, through the rails routine is a junior.
The obvious solution is to abandon your project not too late; leave on a high note.
I also found it very useful to document every step of my setup procedures, right after I figured out what works. At least the respective CL.
It is well known that as soon as you document a setup procedure, it is out of date and needs redocumenting.
I have a special skill of writing terrible code, not seeing it for half a year, and then remembering exactly what the code did
There is a “Not from a Jedi” joke in here somewhere. I can feel it.
I can see that. “This is going to be a problem in the future.” makes it memorable.
That happened to me once. Weird experience. Usually it’s writing terrible code, not seeing it until the next morning and then having no idea what it does.
Could it be the code was so scarring that the pain never left?
deleted by creator
“Code is the documentation”
Is the laziest excuse I’ve come across. Like, not everyone knows everything and complex code exists, it is not hard to put in some text explaining the basics of what something does.
Like, unless you’re dealing with that code everyday it’s going to look like double dutch to anyone new coming to it.
I’ve had people say that to me before, and it is absolutely infuriating in its laziness and cop out excuse.
If someone must explain to me what code does in comments, then I think that code is bad.
Developers invented high-level programming languages for a reason. If someone writes bottom-top, unreadable code with comments, then they might as well write top-bottom, readable code without comments instead. That’s what I believe self-documenting code is.
But if someone explains to me why code does what it does in comments, then that’s fine. Essential complexity exists. The point is that that code is readable already, we know what it does, but not why. That’s what needs an explanation in comments.
deleted by creator
The comments are not for what, they are for why.
The documentation is a summary of the code, a quick guide to the software to more easily find your way to what you need to work with.
Are you saying that when you work with some random library, you skip their documentation and go directly to the source code? That’s absurd. If you do it that way, you’re wasting so much time!
👆 Case in point.
They sound like a great person to work with, “it’s not my fault for lack of documentation, it’s your fault for being an idiot”
The code shows what happens. But comments should explain why it was done this way.
Sometimes the code started simple and readable, till you ran into a weird edge case a year ago. Now the code no longer looks as obvious and another developer might scratch their head when they read over it. A small comment can help out there quite a bit.
Or you’re doing something stupid in code not because you want to, but because management forced you to. So you put a comment there that the code isn’t wrong, management wanted that behavior.
The why can usually be found in Git and issue trackers. Just look at the history of the file to get some decent clue about why a piece of code was programmed in a certain way.
That works for newer projects, but on older projects there’s a dozen commits for any given line and a handful of Jira tickets that have something to do with it, but none that say “Change exactly this”. A comment why you made an interesting design decision costs a lot less time than trying to unwrap the commit history… Especially when you can’t even find a clue on why this was done as the commit might simply be “Implemented feature XY”
I think comments should be a last resort when all other methods are inadequate. Proper git commit logs have helped me many times to understand why a certain thing is needed.
Git logs don’t need maintenance either. They always tell what was true when the code was written. Comments need maintenance, and are often difficult to keep updated.
You can write a detailed comment about the whys of a particular function, only for it to become outdated in weeks when the functionality has changed.
I still haven’t found a proper command or tool to do a multi-commit git blame.
Like I want to know who changed the logic in this line. But the last commit was a format refactor. And the commit before that just changed a tiny detail. So now I’m digging through the entire file history just to find the spot where this one line was introduced or actually changed.
If you have any tips for that, I’m all ears.
I usually use the GUI in IntelliJ for those kind of purposes, but any other GUI might do. Then I perform a manual binary search to find the commit I want.
Ah, I see you don’t optimise enough.
It should be…
Past you “I’ve shed so many lines and boosted processing time. It’s a masterpiece. I should document this for future me because it’s complex as hell.”
Future you “What. The. Hell…” five minutes later “Oh, I see. I’m a fucking narcissist trying to be god of something 10 people run once a week.”
all functions should at least have doc comments on them
No. Just give the function a good descriptive name with good descriptive parameters. Keep the function simple too. If you can’t, try to refactor and see if that helps.
If you are still unable to express yourself via code, then you should use comments to guide the reader.
What about exceptions raised within the function? Will you also put them in the descriptive function name? ;)
You can find them by reading the code. It’s not difficult if they’re placed at proper locations.
But a major point of a function is that you not have to read its implementation details.
According to who? If I have access to the source code, which I often do, I’d rather just read the code. Chances are that if documentation exists, it’s no longer up to date.
Modularity. Part of it is defining a proper Interface for using the hidden complexity.
Exceptions are only one example. Functions can have behavior, inner states, prior calling requirements etc… you cannot read from its mere prototype.
Do you really want everyone to read the inner code to learn that?
Chances are that if documentation exists, it’s no longer up to date.
This risk also applies to descriptive function names. They can be poor, wrong or outdated, too.
This works as a general guideline, but sometimes you aren’t able to write the code in a way that truly self-documents.
If you come back to a function after a month and need half an hour to understand it, you should probably add some comments explaining what was done and why it was done that way (in addition to considering if you should perhaps rewrite it entirely).
If your code is going to be used by third parties, you almost always need more documentation than the raw code.Yes documentation can become obsolete. So constrain its use to cases where it actually adds clarity and commit to keeping it up to date with the evolving code.
`/* Gets CustomerEntity from customer repository by customer ID or throws a customer not found exception */
public CustomerEntity getCustomerEntityById(String customerId){ customerRepository.findById(customerId).orElseThrow(new CustomerNotFoundException()) }`
Of course we forget how it works.
The whole point of the documentation is to help remembering.
An awful lot of people in here talking about automatic comment removal and I … don’t believe it. I think a lot of you are making up stories. Show me proof that a build script removed your comments, because it’s not just bad policy, it’s literally insane. Nobody would do that. Anyone that thought of doing that would spot the folly of doing it within 5 minutes, and immediately stop. GTFO
Let copilot do it. Junior developers can now efficiently write useless comments like the rest of us
I’m very much a novice coder, but I often find myself doing the opposite. Write a good comment and let copilot write the actual code.
Yeah I wouldn’t rely on that, especially early in your coding journey. The less external resources helping you the better, so you’re encouraged to problem solve and figure out your own solutions, even if it takes longer.
I definitely rely on documentation more than copilot, since I’ve noticed that the code it writes is only ever as good as your own codebase.
Most of the stuff I code is API wrappers to get arbitrary data into a format our broadcast graphics system can understand. Once all the data structures are properly defined copilot is extremely useful in populating all the API endpoints.
The actual problem solving is getting the data in the first place and morphing it into the correct format.
Better yet. Only guy who knew the code retires/quits. The next guy who inherits the code finds out nothing was documented and it was all in the previous guy’s head. Next guy has to spend weeks analyzing the code, asking coworkers who shake their heads and buying beers after work to get the previous guy to help him.
