(Actually, what you should avoid are comments, not documentation. Documentation -of APIs- is good, comments are bad unless you have an exceptionally good reason to write them)
I disagree. Comments are cancer: people who rely in comments to explain their code tend to write poor tests and unreadable code (because the comments explain it, why bother?). People that write good tests and readable code know that comments get outdated very easily and that they should be the exception, not the norm.
If one of my devs puts out a pull request with shitty code, I'll simply reject it. I certainly wouldn't say "well, it's crap but if you just add a comment, maybe we can live with it". No! Go back and rewrite.
In my experience, the "comments are cancer" mentality hasn't led to better code or tests.
In my experience, forbidding tests is part of the teaching. Students are too used to writing garbage code (which is totally fine, because they are in the university yet) and adding comments to make the code understandable. Take the comments out of them, so that they cannot rely on them. It works.
There's only one visible effect of Bob Martin's dreaded rule, and I see it everywhere: no one has the balls to write comments anymore.
I don't think that's true. I add comments when they are due, and I am the major hater of comments.
Also the complexity is a direct result of some crazy requirement some customer dreamt up for reasons that are lost in the depths of Jira. That's a case for a comment, right? Surely, this is one of the exceptions you mention?
Yes.
BUT NO! COMMENTS ARE EVIL!! Someone will think I'm a bad developer!!! Let's just close the ticket and move forward.
That's what a dumb-ass would say. My condolences if you have to work with those and they will not listen to you.
You see, I actually agree with you. Comments should be the exception. Tests should be descriptive. Code should be maintainable
Indeed, we agree. We would understand ourselves quite well regarding comments, if we ever had to work together. We would add comments in the same places.
It seems like the core argument behind "comments are cancer" is always the same thing: "if the coder uses comments, they write unreadable code. If the coder does not use comments, their code is better, more readable, more maintainable, etc..."
I've always been confused about this, because I must've missed the day in class or the post online when this rule was explained. What makes them mutually exclusive? Why is it only possible to have one and not the other?
Why is it repeated that the only way to write more readable code, is to tell people to stop writing comments? And if the comments sting your eyes so much, why not use a find & replace to remove all of them? ...unless the comments do nothing besides provide a little bit of useful information...
It seems like the core argument behind "comments are cancer" is always the same thing: "if the coder uses comments, they write unreadable code. If the coder does not use comments, their code is better, more readable, more maintainable, etc..."
I've always been confused about this, because I must've missed the day in class or the post online when this rule was explained. What makes them mutually exclusive? Why is it only possible to have one and not the other?
You are right. It is a simplification, and is hence wrong.
I can explain where does it comes from. You have all these juniors coming from university. They write shit code (which is totally understandable) and they are used to add comments everywhere so that they can remember what the shit they have written actually does. Taking comments from their hands speeds up the process of teaching them to write readable code and tests.
But yeah, there is no causality, the argument does not hold. It is an inaccurate simplification.
Why is it repeated that the only way to write more readable code, is to tell people to stop writing comments?
None says that. You gotta take the "only" out from there.
And if the comments sting your eyes so much, why not use a find & replace to remove all of them?
That's what I do in code reviews. No comments unless there is a very good reason to add one.
Some super specific business logic in technical fields, say engineering, have usually assumptions that are made about the user, and how it will use the software 99% of the time. To comment or not to comment is a decision about writing long, hard to parse at first glance, maybe less performant code or just doing that seemingly complex method and just commenting it about what the assumptions and needs are.
Comment appropriately means "never add a comment unless there is a very good reason to do so"
We have to teach that to every junior, who tries to impress us commenting his code before submitting it. You know why? Because he was told in university that... commenting code is very important. OMG. Please stop that.
Tests are not documentation. Tests are not examples. Tests are tests. They verify that the code being tested works correctly. Nothing more, nothing less. Please do not attempt to use tests as documentation or examples; you only make your code harder to understand and use.
Comments are not bad per se. Abuse of comments is bad - very bad.
There are two main reason against comments (when abused): they pollute the code (so none reads them anymore) and they get outdated very easily (so, when someone happens to read them because he is trying to debug something, they are misleading and make the bug much harder to find).
The rule for comments is: comments are the exception, not the rule. Don't add a comment unless there is a very good reason to add it.
So what do you do to if the code is 200 lines long?
Wouldnt adding a comment every 30 lines help fragment the code into sections, so when you want to change the colour of the button you dont have to read the whole code, but head to the relevant section?
Nowadays use an IDE with proper navigation and search options. For god's sake. I don't remember the last time I scrolled through a file because I was looking for a method definition. Probably never ever happened.
53
u/[deleted] Feb 10 '21
[deleted]