Probably the worst thing about this one is the pydoc. An not just pydoc. Pydoc, javadoc, doxygen. It is all useless garbage that litters the code with useless comments explaining that the get_height method "gets the height" while at the same time nobody is actually explaining anything remotely useful in comments.
This seems a rather broad generalization.. Style guides are certainly very useful specially when pair with auto formatting since they remove a lot of useless arguing.
Sure, we can discuss whether all poiktsw make sense but it seems excessive to dismiss them entirely just because you dislike mandatory method docstrings.
"they remove a lot of useless arguing". It is not like I have not heard this argument before. Unfortunately I have also experienced how it works out in practice. It goes more or less like this. "No, your desired change to the coding style cannot go into the formatting rules because we want to prevent useless arguing so we follow such-and-such style guide to the letter." "Actually, you are not follwing such-and-such style guide to the letter because you these formatting rules are actually not according to such-and-such style guide". "Yes, we decided to have these changes because we think they are good". Utterly despicable.
So besides the useless comments I also have that experience described in the previous paragraph.
And to top it all off, another 'nice' experience with style guides was being forced to used the long discredited 'hungarian notation' which at the time was already long past its expiry date with not really anyone competent believing it to be a good thing.
Maybe my bad experiences are not typical but I have had so many bad experiences with style guides that I am now at the stage where I consider anyone enforcing a style guide to be my personal enemy and most likely a despicable person.
I dont think it is an overgeneralization. Whenever I see lint rules regarding comments applied the comments routinely end up being no shit sherlock comments.
There probably are ways to encourage good comments but enforcing somebody write A comment, ANY comment in specific places at the point when theyre eager to merge is pretty much a recipe for shitty comments.
If you are terrible at writing docs, then that’s your fault, not the style guide’s for enforcing documentation. Some fields might be self-explanatory and the docs for them might be pointless, but it’s better to be overzealous here rather than allow people to skip documenting stuff, because then nothing will be documented.
Also, the requirement to have documentation comments is just one rule out of hundreds, so why focus on that one?
I dissagree that its better to be overzealous here, because it re-enforces the habbit of writing subpar docstrings. Alternatively, if you always do the work (and it is work) to make excellent docstrings, it will affect the way you write code by discouraging splitting code into small obvious functions. It just makes it slightly more annoying.
Just as with comments I think you should assume the reader is a somewhat competent human beeing. Explain what needs to be explained, and make a *conscious* decision about it. For most public functions I agree that this usually involves a docstring, but not always.
Actually, I am quite good at writing docs. That is why I hate mandated comments in certain places. I would like to write better docs than that. In fact your comment tells me you (or perhaps your colleagues) are the one who is terrible at writing docs. "because then nothing will be documented" says it all. I actually would write docs voluntarily and they would actually be helpful.
Why focus on that one? Because it turns out that rule will force me to have 50% of the text that I see in a file be these useless comments.
Some things can’t be linted and require a code reviewer to point them out. Noting the absence of documentation where it is clearly needed would be one of those things.
It forces you to make that decision explicitly. Yes sometimes you just put "Gets the height" and move on. But at least you thought about it and those functions that do need clarification get it because you are reminded of it and the codebase is better for it.
I always roll my eyes, when I see some "documentation" like that. Usually such a community has some overly strict pre-commit hooks you are supposed to use and tons of tooling as well, but the quality of documentation is still bad. Then people lean back and think, that they have good documentation now.
When you dogmatically require that every function must have a comment, that's what happens, regardless of whether it makes sense or not. There's even tools like GhostDoc which will automatically generate useless (and sometimes hilarious) comments for you, just to show how pointless it is, especially when it's only for satisfying another equally useless tool that checks for their presence.
Functions are not usually as obvious as the creator thinks they are.
Does get_height() include the optional border width or not? What does it return while the item is hidden? Does it return an int or float? Can it return a string value like "auto" or a null value? Under what circumstances should its value not be relied upon, e.g. while an animation is active? Why was it written as a function rather than a property? And so forth.
Requiring a comment is helpful in reminding the author to explain why this code was even separated out as a separate function in the first place, and all of the potential gotchas around it.
Now we clearly need to sufficiently document this method by saying "gets the height of the Rectangle in Micrometers".
And yes, this is the garbage kind of answer that one gets whenever one brings up the point that I brought up. Honestly, I am already fondly hoping you will never be a colleague of mine.
This kind of 'documentation' has to be the worst and most disgusting kind of cargo culting ever invented in programming.
You're making the case against comment guidelines: It's poor engineering to resort to a comment to tell you all that.
if get_height returns a simple value, then it "smells" like it should be a simple getter.
So regardless of your comment, people will use it exactly like that and get burnt. Your comment only helps once they're already suffering enough to go digging for why things are so slow.
If the operation needs a DB call it should be exposing a way to handle the infinitely higher likelihood of failure with something like a result type, and it probably shouldn't be a simple blocking call
-
No one is saying you should never have comments by the way, but pydoc-style guidelines where you're encouraged to fill out a template end up with terrible signal to noise.
Comments should be seen as an absolute last resort and a liability.
The only parts of comments that can be automatically refactored are the absolute least useful ones. Things like intent aren't magically be pulled out and updated automatically (yet), so you're now putting the onus on every single person who ever touches that code again to keep your comment up to date, otherwise it's can end up worse than nothing.
Probably the worst thing about this one is the pydoc. An not just pydoc. Pydoc, javadoc, doxygen. It is all useless garbage that litters the code with useless comments explaining that the get_height method "gets the height" while at the same time nobody is actually explaining anything remotely useful in comments.