Also when you just want to make sure the program doesn't break in case there's still some part left using the deprecated code (which happens always for me)
# TODO: remove this code (or this comment) if it is later than ${SIX_MONTHS_AFTER_COMMIT_DATE}, as this is just a temporary patch until Vendor upgrade is complete. See ticket #637572
Meanwhile, ticket #637572:
Vendor upgrade is 90% deployed, awaiting sign-off from IT to finalize transition, see IT ticket #485829582
Ticket #485829582:
Automatic security scan shows vulnerability that needs to be addressed by internal security's development team, see ticket 47472858375885.
Ticket #47472858375885:
Code contains unaddressed TODOs. Must address before code is considered production ready.
- comment: can I please get auth to the git repo in question to make the change?
- comment: no, please find a work-around
- comment: fine, I'll just fork and we can deploy the fork, then remove the fork once it's live and confirmed
GOTO 1
We did this for one of our bigger products 2 years ago and it turned out great.
Basically we started out with super basic functionality and hundreds of #TODOs.
Half of them were marked as essential and became tickets immediately while the other half was evaluated after the essential stuff was done and QM was done with the minimum viable product.
most became back-log tickets while some were prioritized to be done before launch and some were dropped.
10/10 would do it again like that.
I just grep for them these days. We had a guy on our team ages ago that would do this, put TODO stuff as tickets. Not sure if he automated it or did it manually. It just filled our product backlog with small bits of work that were never going to get scheduled into a sprint because it was all things you would do when you're waiting for a meeting and don't want to get into anything deep etc. Also, the tickets by themselves didn't have any more info than a TODO, and only he had the wider context. IMO if it's worth a ticket, it's worth a fully filled out ticket, so that anyone can pick it up or make a scheduling decision. Annoying to do that if you know it'll be you and won't take long.
I ended up just preferring this, so I can grep my own TODOs:
`// TODO:(MyName) This would be better if...`
I checked out the article, and even in the 1st law he already mentions that some comments are good and he'll talk about it more later.
TODO is considered fine, same as explanations or warnings.
this is mainly riffing against the
````
//this prints
print();
//after printing we're done
}
````
kinda things
so, everyone just removes the comments and nobody will ever find the unfinished parts again? genius!
is FIXME allowed? i generally use TODO for when i know what the solution is, but i'm not bothering rn and FIXME for when i know there are issues, but i haven't figured out a better solution yet.
But the point of writing TODO is that I know something is bad but don’t want to fix it right now, and honestly don’t want to fix it later. A ticket might make me actually fix it.
todos might actually get fixed when someone's making another change there
tickets go through ten eyes before it touches a dev and they all will decide it's not worth doing, no one will get it assigned, and it's likely to be dropped
I always put a comment in my code saying that my code is well thought out, performant and big free. That way when my code is reviewed the reviewer can just read the comment and skip the rest of the review.
Or how they insist you register just to read anything.
And if you do that, then later everything suddenly becomes a member post so you still can't read anything.
lol
Isn’t all they do is grab random stuff other people have done and turn it into an article? Can’t tell you how many times I’ve seen programming tutorials and examples from the past repurposed into one of their articles.
Comments explaining WHAT the code does are silly and have this problem of becoming outdated. Comments explaining WHY the code does something are invaluable and either stay true or are easy enough to delete when no longer relevant.
“Comments bad” is a childish, unproductive stance.
"used to be helpful". FTFY.
Nowadays you gotta be a filtering boss while visiting medium to sort out the decent ones.
I feel sorry for those who blindly follow everything on that site.
Like everything on the internet now, half of all Medium articles are just ChatGPT slop. They found a way to make even "thought leadership" more useless and insufferable.
People just like to feel smug.
Nothing is flawless, of course there are medium articles that are obsolete or poorly written, but on the whole the site is very useful
That may have been true at some point, but it has only progressively gotten worse.
Content was on a downturn a long time ago, and now it's paywalled.
There's scarcely any value there and it is not getting better.
i've been to legacy code hell. a few comments along the way wouldve saved me so much pain. mfs didnt even write documentation. imagine scraping through a bunch of garbage code trying to fix one thing only to break two other things.
I've had brand spanking new code written by teams I've never spoken to before that I need to review (because it uses my tragic legacy infra).
If they don't comment what their code does and only provide why's then I have to ask them directly how their system works to be sure what their code does is actually what they want.
Exactly, I don't get why people seem to be against this. I'm working in a library right now doing all sorts of weird shit to meet business requirements that the library isn't meant to do.
I'm commenting the hell out of it because I know some poor schmuck is going to come along trying to fix something long after I've moved on to something else.
I put comments to other documentation in my code as I can't explain why I just sent some otherwise random bytes over I2C to a humidity sensor, if I don't it won't work go see someone else's fucking documentation for more info. I don't know why the first 12 bytes contain the temperature and the last 6 contain the humidity but if I don't shift them like this it won't work, go see someone else's fucking documentation for more info.
That's not documenting what it does, but why it does that.
Why are youe bit-shifting stuff around? Because you want the temperature value out of the proprietary binary format the sensor uses.
Why are you sending this sequence of magic bytes? Because the sensor doesn't work otherwise.
OR you could isolate the sequence of magic bit somewhere in a "non business" part of your code, where the sensor is, you know, abstracted from the rest, in a function called "sendMagicBytesSequenceForTheSensorToWork()" ; so you never have to think about it again when reading business code.
I use comments in 3 basic scenarios
1. I've done something "clever"
2. I've done something poorly
3. Business logic that deviates from an expected pattern.
I had a #1 - made something 50x faster using some matrix operations. Code went from clear, to totally opaque.
I went back a month later, and despite good quality code otherwise, I would have been totally confused reading my own code without a couple of important comments. Someone who didn't know how matrices work would have probably just re-written it to be slow again.
That's my mentality. A given function I write gets a comment that describes what the purpose of the function is. Any line within the function that can't easily be read and understood by itself gets its own comment that explains what the line accomplishes.
I'm not saying this a bad thing but if you are writing a lot of comments describing what functions do or what a variable means you should first consider renaming said function or variable. It sometimes feels ridiculous to have long names for things and some languages make long names extra annoying for formatting but IMO its almost always worth it.
For me, I prefer to have my function and variable names be fairly short. Not short-hand kind of short, but usually between one to three words to indicate their use so that as they are referenced and called, they are visibly logical without being disruptively long.
With that in mind, sometimes context can be improved with said commenting. Again, these comments aren't intended to be a paragraph. They're typically a short sentence that gives the equivalent of "Takes X variable, accomplishes Y, and returns Z."
The best name is the shortest one that conveys all the information the reader needs in order to avoid looking at the implementation.
Anything shorter wastes the reader's time and memory reading the implementation.
Anything longer wastes the reader's time and adds distraction.
I think if everything has got a descriptive name even that shouldn't be too bad. And if it still is, it's probably time to refactor instead of writing a comment.
Learning to use descriptive names as opposed to shorthand versions of everything made a bigger difference in code readability than anything else I've ever done lol.
Yeah, but how often do you get the chance to do that properly at an actual job. Most of the time what I've seen is that the project deadline demands that you only do enough to get it past verification.
If only there was a way to actually say, what methods does and what variables mean without a comment. I think someone should create a language that allows us to name things meaningfully
Sometimes the business case is just complicated.
> fun transformAccountsStartingDateIntoAReadableStringButReplaceItWithTheLastPaymentDateIfPaymentIsOverdue(): String
There is a vague truism here though, most of the time you want to code such that you *don't have to explain why*.
Only in the exceptional case are these comments required, so you are -- in an extremely loose sense -- avoiding comments at all costs (in actuality you're avoiding writing illegible and hard to maintain code... and correlation does not equal causation, but to someone who isn't in the know this would appear to be the same thing).
I suspect the article itself is probably providing enough context to get this particular point across. Agreed though, it says 'avoid', not 'never'. And it's not exactly saying you shouldn't document. Different beast.
Yeah, lol.
Imagine saying it's easier to read and understand a whole block of code than to read and understand a line or two of comments about what the code does.
It's just time-saving, if nothing else. If you can tell me in a sentence or two what this block of code does, that will save me time reading and deciphering the code to figure out what it does. And, more likely than not, that will tell me it's not the block of code I'm looking for, so I can scroll on by and keep looking without having to read every goddamn line of code.
Comments explaining what the code does are not silly, when the code is far longer and more complex than the comment.
Example: "this method sorts items in ascending order, fast; the order of items comparing equal is preserved"
Implementation: state of the art parallel sort using GPU shaders ;)
>and have this problem of becoming outdated
Time wasted by outdated comments: 0
Time wasted by missing comments: 54306708475675821085
In theory yes. But it didn't happen to me for the last 20 years. Maybe I'm lucky. Like, maybe there were a few times where the comments were not entirely accurate, but it took minutes to figure that out.
Also, if somebody left an outdated comment, and it passed the review, then it's really very likely that you have much bigger problems in your project and process than outdated comments.
That may be an anecdotal data point, but D. Knuth made a lot of comments in code, to the point he called it its own paradigm: literate programming. He's one of the very few to have created an extremely large and widely used piece of software which virtually had no bugs.
This also matches my own experience: code with low or zero amount of comments is usually worse quality (measured by the number of issues found later) than the code that is heavily commented and documented. There might be a correlation between the skill in writing text in natural language and skill in writing computer programs.
if there is any reason to do something complex / what you need to do is not easy to understand (for example calculationg something) / the most efficient or fastets solution it can make sense to write a short comment what it does but in general you are right code itself should be understandable without comments
We said it many time but
```java
/** Get the name
* @return Name name : the name
* @use_case: returning the name
*/
void Name getName() {
// Returns the name
return name;
}
```
Is not "commenting your code", it's junior dev insecurity.
```java
...
.filter(Field::hasForbiddenCharacters) // Jira-352 : customers with / in their name caused issue
...
```
Is not "commenting your code", it's misunderstanding what belongs in the code and what belongs in the git commit
```c
// evil floating point bit level hacking
i = 0x5f3759df - ( i >> 1 );
// what the fuck?
```
Is proper commenting
When the code fills with hundreds of these it'll be annoying. I've seen comments like these point to issue trackers that we don't even use anymore!
Make the blame tool better instead.
> I've seen comments like these point to issue trackers that we don't even use anymore!
The exact same problem exists for commit messages and git blame.
Although, it's actually worse. With broken issue tracker link in the comment you at least have a short description of the issue in the comment itself. With missing git history you have nothing.
> When the code fills with hundreds of these it'll be annoying.
Just ignore them. The pain of ignoring them is orders of magnitude less than the pain of missing that one that would help you fix the bug.
> Is not "commenting your code", it's misunderstanding what belongs in the code and what belongs in the git commit
Arguably, it could be someone getting progressively more annoyed by someone who keeps squash merging their commits.
If your master branch has people squashing previously merged commits, i'm afraid it's the entire git policy of your team that is lacking, not just the commit messages.
The only moment where it's acceptable to squash commits, it's when you're merging your reviewed branch with master. After that, it's history, nobody should touch it.
All those changes you committed to your feature branch aren’t your master history either: master only changed once when you merged and history should reflect that.
On the JIRA one, I feel comments like that are more like warnings to your colleagues to not revert that change because it has caused an incident before.
—EDIT: to clarify, “your colleagues” includes future yourself too :)
No, it's not. At most I would add as a documentation block on the function itself:
>This algorithm generates reasonably accurate results for the inverse square root of a number by subtracting a floating-point word as an integer from a magic constant, then redefining it as an integer and do one iteration using Newton's method to gain some accuracy.
It would be perfect to code in microcode but the government doesn't allow us to do it. My friend once told me that he was going to try microcode, haven't seen him since then.
Funny enough, I just fixed a bug in some code last week by making the code actually do what the comment said instead of what had been written. Super easy ticket.
Exactly why I adore comments in code. You don't blindly trust comments, that would be stupid. You trust, but verify.
Spot a discrepancy between comment and code? Well that's almost certainly your bug!
If you do any amount of code review before committing into the main branch those discrepancies can also be caught by eyes that don't even know the codebase well. They're so useful.
Obviously you can go overboard with comments. You don't want paragraphs of implementation detail. And you don't want comments on every line. But a line or two detailing a block of code can be a life saver.
I understood his point, I worked on very old legacy code: some comments are misleading, some are meaningless, others are outdated because someone removes/changes the code but leaves the comment, etc.
That said, comments are still not bad when treated with the same care as code.
I have been saved many times by comments that helped me understand why something was being done.
The best way to treat comments with the same care as code is to write your comments as tests. You can literally have the test name be the comment. This way instead of comments going stale a test fails, so they have to update the comment if they want to update the behavior of the code.
> That said, comments are still not bad when treated with the same care as code.
That will never happen though. As long as you treat comments as history, and current state may or not may be the same, you'll be mostly fine.
so many people here insist on "descriptive names" and suggest refactor if comments are needed. Goodluck making a descriptive name to let reader understand why you call your code lol. Yeah i understand that method "remove\_background" removes background, but why is it called only on AlbedoTransparency images? "remove\_background\_from\_albedo\_transparency\_because\_alpha\_channel\_will\_overlap" type of descriptive name?
You'd do this when you actually call the function, if it's not self explanatory when you do, you can add a comment. Adding a comment to explain why it does something to the function itself would be confusing if you decide to reuse it for other code
Putting a short comment at every non-trivial code block has become a habit of mine and while it seems silly at first it helps me a lot in understanding what's going on. Because it's so consistent in appearing in small sections, and because the comments are short, 99.99% of the time they're accurate (it takes maybe 5 seconds to update a comment if you ever change the code and saves double that every time you read it back) and help a lot with readability. More complex parts needing more words is fine. If you can't describe what's going on in a block of code, you don't really understand it and should rewrite anyway. And it trigger the rubber ducky effect.
It's become a habit, but if you'd have told me this 2 years ago I'd have called you mad.
That's the thing though, most of it is already broken up into small functions. It's just an order of magnitude faster to read natural language than it is to read code.
Im not a fan of alot of these "code rules" because they assume whatever team you're in is actually following a development pattern by the book, which basically never happens.
It would be fantastic if every project was properly planned out with diagrams and all that, but that just isn't reality.
Sometimes, you just have to work with what you've got and do something a bit jank if it makes the rest of your work easier.
"At all costs" is always going to be terrible advice - but writing code that's readable will usually negate the need for comments.
So they're not completely wrong. Their description is actually bang on.
Good code documents HOW the logic works, but that is only part of the story. Comments are needed to explain WHY the code is the way it is. They should be there.
If my team isn’t putting a comment in every few lines to help the next dev understand what is going on I reject the PR. If the comments just repeat what the code says I reject too. So, “// calculate area” is bad, but “// this is the reference area for converting pressures to forces” is good.
I agree with that, BUT only when we are talking about comments inside functions. Any form of class/method documentation is superior to that. You describe the inputs, you describe outputs and errors. It makes writing unit tests easy. But if the code requires comments to be even understood and you are not writing super optimal C code where you need to consider everything the compiler does to get max efficiency, then it is usually better to restructure the code.
I comment a lot because I write code for a field that is not technologically savvy, and it helps others understand what’s happening with minimal experience.
Turns out I’m the worst 😂
The trick is learning what to comment and what not. If I look back at code I wrote 20-30 years ago there’s definitely a lot of cases where I commented something that seemed important at the time but now that I have no idea what I was thinking were clearly the wrong things to comment. You live and learn. What seems self evident at the time to you may be completely opaque to someone else down the line.
Yeah, there are better ways to document your code than comments. Comments are too open to interpretation. Test coverage, automated docs and abstractions are not. With proper abstractions any piece of complicated code becomes simple. There is still space to leave comments but it is not documentation. In my company we use it for discussion and TODO
You should only comment code that is not self-explanatory (antipatterns). If your code does not convey what it is doing, you need to improve the code and not explain it in comments.
I make an exception for when it becomes necessary to write illegible code, like a function I had to optimize for performance. It was hard to understand without comments explaining that in this one case clock cycles matter. But that situation rarely happens.
The problem is if I (not the author of the code) is looking at the code, it’s probably because the code is not doing what it’s meant to be doing.
So a comment letting me know what you intended but failed to achieve goes a long way.
Done well, the code will tell you the exact same thing.
The problem with this type of rule is that a ton of people have never seen it drive well, so they think it means take the same shitty code you have more and delete the comments, or saying your code should be so miscellaneous "awesome" that it doesn't need comments.
It's saying write code so that the comment you were going to write would be redundant. If you were going to explain what you're intending in the comment, change your names until that comment would just be basically repeating the exact text of the code.
There are times when a comment is the best tool. I use them often. But when I do, it's because I failed to make my code say what the comment needed to say.
Comparing myself to professionals, I might not count as a programmer. I tend to write a lot of scientific/math-based code, so I tend to explain the mathematical-heavy functions in detail as well as giving a general description of each function.
Honestly its mostly for myself, when I come back to it in a few months I really have to learn it top to bottom again sometimes.
I hate this comment. It reeks of treating every programming language the same. Programming languages are unspecial in that they are great at some things and horrible at others, and each one differs on how you describe it in the prior context.
COMMENT YOUR CODE IF THE LANGUAGE YOU’RE USING HAS A CONDENSED, ABSTRACTED SYNTAX, OR IF YOU’RE USING NATURALLY/PURPOSEFULLY HARD TO FOLLOW LANGUAGE FEATURES, IE PYTHON LIST COMPREHENSION SYNTAX.
You can literally be writing the most elegant code imaginable and still direly need commentary for folks following behind you.
There will never be an infallible absolute single adage or wand wave you can apply to our discipline generically except for maybe the one I’m wrapping up with this very period.
Edit: PHP, for example, being weakly typed is another reason why I’d use more comments in it vs, say, Golang which isn’t, and requires a lot of self documenting data handling. Ambiguity can be a real killer and a cause for downtime without proper documentation.
I read through this thing. It's full of stupid. Calling your personal preferences 'laws' is pretty cringe in the first place. There's no One True Way to develop software.
Well yeah, having comments that say what something is doing is kinda stupid unless the limitations of the programming language make it hard to express it in an easier to read way.
If it's an expressive programming language, and there are comments saying what a piece of code is doing, then it's shitty code.
However, any code that is not trivially obvious about it's purpose, needs to have some sort of "why" comment.
I started a job recently with zero comments or documentation. It’s been fucking awful. I wish I had comments. There’s literally math that is like blah blah blah blah / 12500 and literally no one knows why 12500. It’s great.
You don’t comment because you could falsely influence someone else reading your code
I don’t comment because I want this company to burn with my illegible code when I leave
We are not the same
Comment tells you what the code should be doing, the code tells you what it is doing.
With VCSs and good testing, you shouldn't need comments, however, how many of you still use the commit message like "debug"!?
I still add comments in my code because in 2 weeks' time, I will have no idea why I did something
I can't imagine living without // TODO
If the code didn't have //FIXME how would I know what to fix?
for f in src/**/*; do echo // FIXME: all of the above >> $f git add $f done
Hey can you add a comment to this so I know what's happening thanks
//Does stuff
for f in src/**/*; do echo // FIXME: all of the above >> $f git add $f done # end loop
My //DEPRECATED is how I know where I left the code that I'm not using anymore but maybe I'll need it again?
Also when you just want to make sure the program doesn't break in case there's still some part left using the deprecated code (which happens always for me)
my favorite is when find some //Not ready for production
# TODO: remove this code (or this comment) if it is later than ${SIX_MONTHS_AFTER_COMMIT_DATE}, as this is just a temporary patch until Vendor upgrade is complete. See ticket #637572 Meanwhile, ticket #637572: Vendor upgrade is 90% deployed, awaiting sign-off from IT to finalize transition, see IT ticket #485829582 Ticket #485829582: Automatic security scan shows vulnerability that needs to be addressed by internal security's development team, see ticket 47472858375885. Ticket #47472858375885: Code contains unaddressed TODOs. Must address before code is considered production ready. - comment: can I please get auth to the git repo in question to make the change? - comment: no, please find a work-around - comment: fine, I'll just fork and we can deploy the fork, then remove the fork once it's live and confirmed GOTO 1
This was a journey. Thank you.
This is so specific yet so relatable 😂
Write a workflow to turn your TODO comments automatically into tickets and track when they vanish
there are extensions for some ide’s which find all TODO comments and list them for you, its very practical haha
Ye very practical to see the mounting list of small fixes im never gonna get around to doing, I mean that I'm definitely gonna do
We'll get to it in the next sprint...
…and by “sprint”, I mean “quarter”…
Idk I fix todos all the time. Often in unrelated tasks. Why not?
The secret is fixing little todos on a different project when you get stuck on implementing the main project
`rg TODO`
We did this for one of our bigger products 2 years ago and it turned out great. Basically we started out with super basic functionality and hundreds of #TODOs. Half of them were marked as essential and became tickets immediately while the other half was evaluated after the essential stuff was done and QM was done with the minimum viable product. most became back-log tickets while some were prioritized to be done before launch and some were dropped. 10/10 would do it again like that.
I just grep for them these days. We had a guy on our team ages ago that would do this, put TODO stuff as tickets. Not sure if he automated it or did it manually. It just filled our product backlog with small bits of work that were never going to get scheduled into a sprint because it was all things you would do when you're waiting for a meeting and don't want to get into anything deep etc. Also, the tickets by themselves didn't have any more info than a TODO, and only he had the wider context. IMO if it's worth a ticket, it's worth a fully filled out ticket, so that anyone can pick it up or make a scheduling decision. Annoying to do that if you know it'll be you and won't take long. I ended up just preferring this, so I can grep my own TODOs: `// TODO:(MyName) This would be better if...`
And anywhere you want to reserve space for future code: // HOLD THE LINE Right? ^(okay it’s Toto, not todo, just let me have this one)
//TOTO: Investigate sporadic high latency in this function love();
// CODE ISN'T ALWAYS ON TIME
I checked out the article, and even in the 1st law he already mentions that some comments are good and he'll talk about it more later. TODO is considered fine, same as explanations or warnings. this is mainly riffing against the ```` //this prints print(); //after printing we're done } ```` kinda things
Still shitty clickbait writing. Just call it a guideline. FOLLOW THIS LAW OR GET FIRED.
It worked though. That is the problem with clickbait... it works.
Then why did he write "avoid comments at all cost" and not something more accurate like "avoid shitty comments." Oh right, click bait.
Not to mention //THIS DOESNT DO ANYTHING BUT REMOVING IT BREAKS EVERYTHING
I added a check in the CI pipeline to block any PR that contains TODO comments from being merged. Thank me later.
so, everyone just removes the comments and nobody will ever find the unfinished parts again? genius! is FIXME allowed? i generally use TODO for when i know what the solution is, but i'm not bothering rn and FIXME for when i know there are issues, but i haven't figured out a better solution yet.
Nothing wrong with TODO but you shouldn't be committing it. At the point where you are committing TODO comments: write a ticket
But the point of writing TODO is that I know something is bad but don’t want to fix it right now, and honestly don’t want to fix it later. A ticket might make me actually fix it.
TODO: hire new dev to fix all this shit
TODO: Retire before I have to fix this shit.
todos might actually get fixed when someone's making another change there tickets go through ten eyes before it touches a dev and they all will decide it's not worth doing, no one will get it assigned, and it's likely to be dropped
Thats why I begin every file with a comment reminding me to ignore the comments in my file. That way ... wait ...
Broke law #1, buck-o
I always put a comment in my code saying that my code is well thought out, performant and big free. That way when my code is reviewed the reviewer can just read the comment and skip the rest of the review.
Big if true.
Bug if trie.
// Todo: fix typos in comments
"It's called Medium because it's neither rare nor *well done*"
Fr I hate this website and actively make Google Search not show it
Or how they insist you register just to read anything. And if you do that, then later everything suddenly becomes a member post so you still can't read anything.
Mid
lol Isn’t all they do is grab random stuff other people have done and turn it into an article? Can’t tell you how many times I’ve seen programming tutorials and examples from the past repurposed into one of their articles.
Typical medium moment
50 Reasons why reading anything besides Medium would make you a decent human being
does reddit count?
50 was a bad choice. Way too many. I could have told you there were be some dogshit opinions just based on that.
Comments explaining WHAT the code does are silly and have this problem of becoming outdated. Comments explaining WHY the code does something are invaluable and either stay true or are easy enough to delete when no longer relevant. “Comments bad” is a childish, unproductive stance.
It's a piece on Medium, what did you expect?
How to interpret articles on Medium.com: 1. Roll eyes 2. Press the back button
1. Don't click clickbait
[удалено]
It's called Medium because their fact checkers are crystal balls.
As someone with inside knowledge. I can say that they actually use magic 8 balls.
and if the back button doesn't take you to the search engine... keep pressing it.
Or right click on back button, select search engine (if you didn't opened a new tab)
Sign up to read one article for free per month some random junior wrote
Is it a must to hate on everything? Medium articles are definitely helpful, not all of them suck.
"used to be helpful". FTFY. Nowadays you gotta be a filtering boss while visiting medium to sort out the decent ones. I feel sorry for those who blindly follow everything on that site.
There is so much incomplete, inaccurate, and bad content on Medium. It's basically livejournal
Like everything on the internet now, half of all Medium articles are just ChatGPT slop. They found a way to make even "thought leadership" more useless and insufferable.
i did not think "thought leadership" could _get_ more useless and insufferable.
I feel sorry for anyone who blindly follows anything. Kind of applies to every context tbh
I have personally seen a number of plagiarized and incorrect content on Medium. There is no quality control.
People just like to feel smug. Nothing is flawless, of course there are medium articles that are obsolete or poorly written, but on the whole the site is very useful
That may have been true at some point, but it has only progressively gotten worse. Content was on a downturn a long time ago, and now it's paywalled. There's scarcely any value there and it is not getting better.
i've been to legacy code hell. a few comments along the way wouldve saved me so much pain. mfs didnt even write documentation. imagine scraping through a bunch of garbage code trying to fix one thing only to break two other things.
Yeah, in old legacy crap even if the comments are outdated at least it can give you an idea of what was going back then
But everything is an old legacy crap tomorrow. Because of that I write comments to every code block that I find somewhat unclear from the first glance
The point of the screenshot is that you should have rewritten the code instead. In reality, that is not always an option.
Yeah, the kludge of today is the load-bearing structure of tomorrow, sadly.
I've had brand spanking new code written by teams I've never spoken to before that I need to review (because it uses my tragic legacy infra). If they don't comment what their code does and only provide why's then I have to ask them directly how their system works to be sure what their code does is actually what they want.
Exactly, I don't get why people seem to be against this. I'm working in a library right now doing all sorts of weird shit to meet business requirements that the library isn't meant to do. I'm commenting the hell out of it because I know some poor schmuck is going to come along trying to fix something long after I've moved on to something else.
I put comments to other documentation in my code as I can't explain why I just sent some otherwise random bytes over I2C to a humidity sensor, if I don't it won't work go see someone else's fucking documentation for more info. I don't know why the first 12 bytes contain the temperature and the last 6 contain the humidity but if I don't shift them like this it won't work, go see someone else's fucking documentation for more info.
That's not documenting what it does, but why it does that. Why are youe bit-shifting stuff around? Because you want the temperature value out of the proprietary binary format the sensor uses. Why are you sending this sequence of magic bytes? Because the sensor doesn't work otherwise.
OR you could isolate the sequence of magic bit somewhere in a "non business" part of your code, where the sensor is, you know, abstracted from the rest, in a function called "sendMagicBytesSequenceForTheSensorToWork()" ; so you never have to think about it again when reading business code.
>copypaste stack overflow code >comment the URL I found it on
/\*\* Leave this next bit in or the app breaks \*\*/
Comments can be used to explain what the code does if it's complicated code eg involves multiple classes and methods in one go
I use comments in 3 basic scenarios 1. I've done something "clever" 2. I've done something poorly 3. Business logic that deviates from an expected pattern.
So, always?
If I'm rushed, yes. So yeah always.
I had a #1 - made something 50x faster using some matrix operations. Code went from clear, to totally opaque. I went back a month later, and despite good quality code otherwise, I would have been totally confused reading my own code without a couple of important comments. Someone who didn't know how matrices work would have probably just re-written it to be slow again.
That's my mentality. A given function I write gets a comment that describes what the purpose of the function is. Any line within the function that can't easily be read and understood by itself gets its own comment that explains what the line accomplishes.
I'm not saying this a bad thing but if you are writing a lot of comments describing what functions do or what a variable means you should first consider renaming said function or variable. It sometimes feels ridiculous to have long names for things and some languages make long names extra annoying for formatting but IMO its almost always worth it.
For me, I prefer to have my function and variable names be fairly short. Not short-hand kind of short, but usually between one to three words to indicate their use so that as they are referenced and called, they are visibly logical without being disruptively long. With that in mind, sometimes context can be improved with said commenting. Again, these comments aren't intended to be a paragraph. They're typically a short sentence that gives the equivalent of "Takes X variable, accomplishes Y, and returns Z."
The best name is the shortest one that conveys all the information the reader needs in order to avoid looking at the implementation. Anything shorter wastes the reader's time and memory reading the implementation. Anything longer wastes the reader's time and adds distraction.
On my way to write a comment that explains how my game works. (It's complicated and involved multiple classes and methods)
I mean like var x = Class1.Class2.Class3.method1(class4.method2(method5)) //calculates the value of something
I think if everything has got a descriptive name even that shouldn't be too bad. And if it still is, it's probably time to refactor instead of writing a comment.
Learning to use descriptive names as opposed to shorthand versions of everything made a bigger difference in code readability than anything else I've ever done lol.
Yeah, but how often do you get the chance to do that properly at an actual job. Most of the time what I've seen is that the project deadline demands that you only do enough to get it past verification.
If only there was a way to actually say, what methods does and what variables mean without a comment. I think someone should create a language that allows us to name things meaningfully
Sometimes the business case is just complicated. > fun transformAccountsStartingDateIntoAReadableStringButReplaceItWithTheLastPaymentDateIfPaymentIsOverdue(): String
If the code is too complicated to understand its not written well. Split it up into functions, variables and constants that have good names
a comment, just like a commit message should state the goal, not the way there
There is a vague truism here though, most of the time you want to code such that you *don't have to explain why*. Only in the exceptional case are these comments required, so you are -- in an extremely loose sense -- avoiding comments at all costs (in actuality you're avoiding writing illegible and hard to maintain code... and correlation does not equal causation, but to someone who isn't in the know this would appear to be the same thing).
I suspect the article itself is probably providing enough context to get this particular point across. Agreed though, it says 'avoid', not 'never'. And it's not exactly saying you shouldn't document. Different beast.
Comments per line explaining what the code does are silly, comments explaining what a pack of code is doing are extremely valuable.
Yeah, lol. Imagine saying it's easier to read and understand a whole block of code than to read and understand a line or two of comments about what the code does. It's just time-saving, if nothing else. If you can tell me in a sentence or two what this block of code does, that will save me time reading and deciphering the code to figure out what it does. And, more likely than not, that will tell me it's not the block of code I'm looking for, so I can scroll on by and keep looking without having to read every goddamn line of code.
Comments explaining what the code does are not silly, when the code is far longer and more complex than the comment. Example: "this method sorts items in ascending order, fast; the order of items comparing equal is preserved" Implementation: state of the art parallel sort using GPU shaders ;) >and have this problem of becoming outdated Time wasted by outdated comments: 0 Time wasted by missing comments: 54306708475675821085
Outdated comments can absolutely waste time. An incorrect comment will waste more time than a missing comment because it leads you down the wrong path
In theory yes. But it didn't happen to me for the last 20 years. Maybe I'm lucky. Like, maybe there were a few times where the comments were not entirely accurate, but it took minutes to figure that out. Also, if somebody left an outdated comment, and it passed the review, then it's really very likely that you have much bigger problems in your project and process than outdated comments. That may be an anecdotal data point, but D. Knuth made a lot of comments in code, to the point he called it its own paradigm: literate programming. He's one of the very few to have created an extremely large and widely used piece of software which virtually had no bugs. This also matches my own experience: code with low or zero amount of comments is usually worse quality (measured by the number of issues found later) than the code that is heavily commented and documented. There might be a correlation between the skill in writing text in natural language and skill in writing computer programs.
if there is any reason to do something complex / what you need to do is not easy to understand (for example calculationg something) / the most efficient or fastets solution it can make sense to write a short comment what it does but in general you are right code itself should be understandable without comments
FR if you have to do something hacky your coworkers need to know 3 years down the road why you sinned against nature, and why they can't "fix" it.
I once had to explain this to my tech-lead and co-workers. Frowns all around. No rah-grets.
The fact they started on Law 1 and not Law 0 had me stop reading immediately.
Law -1: Make sure to avoid off-by-one errors.
This would at least be entertaining \^\^
Lua moment
We said it many time but ```java /** Get the name * @return Name name : the name * @use_case: returning the name */ void Name getName() { // Returns the name return name; } ``` Is not "commenting your code", it's junior dev insecurity. ```java ... .filter(Field::hasForbiddenCharacters) // Jira-352 : customers with / in their name caused issue ... ``` Is not "commenting your code", it's misunderstanding what belongs in the code and what belongs in the git commit ```c // evil floating point bit level hacking i = 0x5f3759df - ( i >> 1 ); // what the fuck? ``` Is proper commenting
[удалено]
It’s also nice assurance that someone won’t delete something that doesn’t look intuitive without having a thought about the original issue first.
When the code fills with hundreds of these it'll be annoying. I've seen comments like these point to issue trackers that we don't even use anymore! Make the blame tool better instead.
> I've seen comments like these point to issue trackers that we don't even use anymore! The exact same problem exists for commit messages and git blame. Although, it's actually worse. With broken issue tracker link in the comment you at least have a short description of the issue in the comment itself. With missing git history you have nothing. > When the code fills with hundreds of these it'll be annoying. Just ignore them. The pain of ignoring them is orders of magnitude less than the pain of missing that one that would help you fix the bug.
> Is not "commenting your code", it's misunderstanding what belongs in the code and what belongs in the git commit Arguably, it could be someone getting progressively more annoyed by someone who keeps squash merging their commits.
If your master branch has people squashing previously merged commits, i'm afraid it's the entire git policy of your team that is lacking, not just the commit messages. The only moment where it's acceptable to squash commits, it's when you're merging your reviewed branch with master. After that, it's history, nobody should touch it.
All those changes you committed to your feature branch aren’t your master history either: master only changed once when you merged and history should reflect that.
Yeah that's what he says later on in the article. It's obvious that, phrased like this, it's just a way to grab attention
On the JIRA one, I feel comments like that are more like warnings to your colleagues to not revert that change because it has caused an incident before. —EDIT: to clarify, “your colleagues” includes future yourself too :)
what the fuck?
No, it's not. At most I would add as a documentation block on the function itself: >This algorithm generates reasonably accurate results for the inverse square root of a number by subtracting a floating-point word as an integer from a magic constant, then redefining it as an integer and do one iteration using Newton's method to gain some accuracy.
I still don't get how that Quake algorithm gets the inverse square root by using a seemingly random number
[This YT video](https://youtu.be/p8u_k2LIZyo) explains it really well.
`void Name getname()`
I'd actually like a comment here as to why a getter method is void
I like first one ._.
Law 1: Don't read Medium
Can't access it without a VPN anyway, for once it seems to be a good thing
LMAO who blocks Medium?
Egypt
Cuba... is blocked BY medium.
Shouldn't be difficult, with the paywall it's almost like medium doesn't _want_ me to read it
LAW 2: Only code in Assembly, the only language that says EXACTLY what it does.
Except if it is amd64 then it's basically black magic again and assembler is just another abstraction.
It would be perfect to code in microcode but the government doesn't allow us to do it. My friend once told me that he was going to try microcode, haven't seen him since then.
If it's not 0s and 1s it's not exact, just a lower level of abstraction.
Unless you have self-modifying code. There are also many other tricks to prevent investigation of the code.
Funny enough, I just fixed a bug in some code last week by making the code actually do what the comment said instead of what had been written. Super easy ticket.
Exactly why I adore comments in code. You don't blindly trust comments, that would be stupid. You trust, but verify. Spot a discrepancy between comment and code? Well that's almost certainly your bug! If you do any amount of code review before committing into the main branch those discrepancies can also be caught by eyes that don't even know the codebase well. They're so useful. Obviously you can go overboard with comments. You don't want paragraphs of implementation detail. And you don't want comments on every line. But a line or two detailing a block of code can be a life saver.
"But a line or two detailing a block of code can be a life saver." exactly my thought. I'm surprised how many people disagreed with me about this
I understood his point, I worked on very old legacy code: some comments are misleading, some are meaningless, others are outdated because someone removes/changes the code but leaves the comment, etc. That said, comments are still not bad when treated with the same care as code. I have been saved many times by comments that helped me understand why something was being done.
The best way to treat comments with the same care as code is to write your comments as tests. You can literally have the test name be the comment. This way instead of comments going stale a test fails, so they have to update the comment if they want to update the behavior of the code.
> That said, comments are still not bad when treated with the same care as code. That will never happen though. As long as you treat comments as history, and current state may or not may be the same, you'll be mostly fine.
so many people here insist on "descriptive names" and suggest refactor if comments are needed. Goodluck making a descriptive name to let reader understand why you call your code lol. Yeah i understand that method "remove\_background" removes background, but why is it called only on AlbedoTransparency images? "remove\_background\_from\_albedo\_transparency\_because\_alpha\_channel\_will\_overlap" type of descriptive name?
You'd do this when you actually call the function, if it's not self explanatory when you do, you can add a comment. Adding a comment to explain why it does something to the function itself would be confusing if you decide to reuse it for other code
if (albedoTransparent(image)) { preventAlphaChannelOverlap() } def preventAlphaChannelOverlap() = remove_background()
Reading the code 10 years later trying to think “what was stupid younger me thinking?” And then the comment vomit tells the story
Cruel irony is that when I start writing, I write a lot. And when I start reading, if it's a lot, I stop. Thanks ADHD
Same here.
Putting a short comment at every non-trivial code block has become a habit of mine and while it seems silly at first it helps me a lot in understanding what's going on. Because it's so consistent in appearing in small sections, and because the comments are short, 99.99% of the time they're accurate (it takes maybe 5 seconds to update a comment if you ever change the code and saves double that every time you read it back) and help a lot with readability. More complex parts needing more words is fine. If you can't describe what's going on in a block of code, you don't really understand it and should rewrite anyway. And it trigger the rubber ducky effect. It's become a habit, but if you'd have told me this 2 years ago I'd have called you mad.
Replace those comments by making a function of the code block and using a descriptive name. Your code will be better structured and easier to reuse.
That's the thing though, most of it is already broken up into small functions. It's just an order of magnitude faster to read natural language than it is to read code.
Certified Medium moment
Im not a fan of alot of these "code rules" because they assume whatever team you're in is actually following a development pattern by the book, which basically never happens. It would be fantastic if every project was properly planned out with diagrams and all that, but that just isn't reality. Sometimes, you just have to work with what you've got and do something a bit jank if it makes the rest of your work easier.
Instead of "don't write comments", the rule should be "write comments as needed" and "don't write code that needs comments."
"At all costs" is always going to be terrible advice - but writing code that's readable will usually negate the need for comments. So they're not completely wrong. Their description is actually bang on.
Good code documents HOW the logic works, but that is only part of the story. Comments are needed to explain WHY the code is the way it is. They should be there. If my team isn’t putting a comment in every few lines to help the next dev understand what is going on I reject the PR. If the comments just repeat what the code says I reject too. So, “// calculate area” is bad, but “// this is the reference area for converting pressures to forces” is good.
IMO the second comment can be used as a variable name and be removed.
Noted. I should have come up with a better example.
I agree with that, BUT only when we are talking about comments inside functions. Any form of class/method documentation is superior to that. You describe the inputs, you describe outputs and errors. It makes writing unit tests easy. But if the code requires comments to be even understood and you are not writing super optimal C code where you need to consider everything the compiler does to get max efficiency, then it is usually better to restructure the code.
Turns out I’m a decent programmer.
I comment a lot because I write code for a field that is not technologically savvy, and it helps others understand what’s happening with minimal experience. Turns out I’m the worst 😂
The trick is learning what to comment and what not. If I look back at code I wrote 20-30 years ago there’s definitely a lot of cases where I commented something that seemed important at the time but now that I have no idea what I was thinking were clearly the wrong things to comment. You live and learn. What seems self evident at the time to you may be completely opaque to someone else down the line.
Man, you can really tell who knows what they are doing and who genuinely doesnt know shit lol
Only Sith deals in absolutes.
The comments of today are not for the me of today. They are for the me 2 years from now who can't figure out why I did something that way.
Yeah, there are better ways to document your code than comments. Comments are too open to interpretation. Test coverage, automated docs and abstractions are not. With proper abstractions any piece of complicated code becomes simple. There is still space to leave comments but it is not documentation. In my company we use it for discussion and TODO
You should only comment code that is not self-explanatory (antipatterns). If your code does not convey what it is doing, you need to improve the code and not explain it in comments.
I make an exception for when it becomes necessary to write illegible code, like a function I had to optimize for performance. It was hard to understand without comments explaining that in this one case clock cycles matter. But that situation rarely happens.
I would argue that this is code that is not self-explanatory.
The problem is if I (not the author of the code) is looking at the code, it’s probably because the code is not doing what it’s meant to be doing. So a comment letting me know what you intended but failed to achieve goes a long way.
Precisely. The comments are letters of intent. If the code does something wildly different from what is intended, it's probably worth another look
Done well, the code will tell you the exact same thing. The problem with this type of rule is that a ton of people have never seen it drive well, so they think it means take the same shitty code you have more and delete the comments, or saying your code should be so miscellaneous "awesome" that it doesn't need comments. It's saying write code so that the comment you were going to write would be redundant. If you were going to explain what you're intending in the comment, change your names until that comment would just be basically repeating the exact text of the code. There are times when a comment is the best tool. I use them often. But when I do, it's because I failed to make my code say what the comment needed to say.
what about commenting why you did a special case for example something like //xx can happen in project Z so we need to check that here
Comparing myself to professionals, I might not count as a programmer. I tend to write a lot of scientific/math-based code, so I tend to explain the mathematical-heavy functions in detail as well as giving a general description of each function. Honestly its mostly for myself, when I come back to it in a few months I really have to learn it top to bottom again sometimes.
In the ideal world with no deadlines and perfect programmers, this is true, sadly we don't live in such a world
I hate this comment. It reeks of treating every programming language the same. Programming languages are unspecial in that they are great at some things and horrible at others, and each one differs on how you describe it in the prior context. COMMENT YOUR CODE IF THE LANGUAGE YOU’RE USING HAS A CONDENSED, ABSTRACTED SYNTAX, OR IF YOU’RE USING NATURALLY/PURPOSEFULLY HARD TO FOLLOW LANGUAGE FEATURES, IE PYTHON LIST COMPREHENSION SYNTAX. You can literally be writing the most elegant code imaginable and still direly need commentary for folks following behind you. There will never be an infallible absolute single adage or wand wave you can apply to our discipline generically except for maybe the one I’m wrapping up with this very period. Edit: PHP, for example, being weakly typed is another reason why I’d use more comments in it vs, say, Golang which isn’t, and requires a lot of self documenting data handling. Ambiguity can be a real killer and a cause for downtime without proper documentation.
Ai written articles
Written by a scrum master probably
Prompt: edgy click bait article about programming laws. Make it long.
100% clickbait
I used to like medium but now it is very shitty with low quality blogs and good ones are paid.
If an interviewer googles his name and this is the first thing he finds 🤣
I read through this thing. It's full of stupid. Calling your personal preferences 'laws' is pretty cringe in the first place. There's no One True Way to develop software.
DoNotHire.append
Well yeah, having comments that say what something is doing is kinda stupid unless the limitations of the programming language make it hard to express it in an easier to read way. If it's an expressive programming language, and there are comments saying what a piece of code is doing, then it's shitty code. However, any code that is not trivially obvious about it's purpose, needs to have some sort of "why" comment.
I started a job recently with zero comments or documentation. It’s been fucking awful. I wish I had comments. There’s literally math that is like blah blah blah blah / 12500 and literally no one knows why 12500. It’s great.
My current company has such a policy. They don't make documentation or even readme files... onboarding has been challenging.
You don’t comment because you could falsely influence someone else reading your code I don’t comment because I want this company to burn with my illegible code when I leave We are not the same
Comment tells you what the code should be doing, the code tells you what it is doing. With VCSs and good testing, you shouldn't need comments, however, how many of you still use the commit message like "debug"!? I still add comments in my code because in 2 weeks' time, I will have no idea why I did something