DEV Community

Code Smell 224 - Deodorant Comments

Maxi Contieri on September 10, 2023

You use nice words to excuse bad code TL;DR: Don't excuse bad code. Write a clean one! Problems Readability Solutions ...

Read full post

Alex Lohr • Sep 11 '23

In general, comments describing anything else than the copyright or the non-obvious reasoning behind the code should be avoided.

Jan Küster • Sep 20 '23

Agree but I also found that if I use comments for "non-obvious reasoning behind the code" I found that these should in contrast be as precise and detailed as possible. Saved me lots of time when looking at older code after a year.
Plus: If comments are rarely used and then this one comment block is long and detailed it might be of importance to read :-)

Thibaut Andrieu • Sep 12 '23

Every rules has its exception.

Unfortunately, if the method is already part of exposed API used by your customers, you cannot simply rename it. Either you deal with it and add a comment explaining what it actually do, either you go through painfull deprecation process.

The best is to catch it before it actually go into the wild. Code review is your friend here !

lionel-rowe • Sep 11 '23

I disagree that "adder" and "anotherAdder" are good param names. "Adder" is a specific term in computer science/electronics, referring to an ALU component that performs binary addition. Given it would be unlikely to refer to that in a high-level language like python, I'd assume instead it was either a function or an instance of a class that performs addition. A number passed as a param isn't an active agent, as implied by "-er" suffix — it doesn't add itself, rather addition is performed on it.

Apparently "augend" and "addend" are sometimes used to refer to the 2 operands in addition, but IMO those are far too academic for general-purpose usage. "number1" and "number2" are easy to understand in the context of summing, and the function name sum tells us what's going to happen to them.

Vincent A. Cicirello • Sep 11 '23

I think you may have partially missed his point that the word "number" in the variable name specifies the type of value rather than its purpose. Types rarely, if ever, belong in variable names. In Python, they don't necessarily need to be "numbers" with operator overloading. They could be, but they could also be objects of some matrix class, or something else that makes sense to sum.

Using the actual name, "addend", for the arguments of an addition would be better (he just had the name for it wrong but was clearly his intention). However, going with your point, the function name does make it clear what it does. So more generic names for the parameters might be OK. But in that case, just go with something like x and y, or maybe x1 and x2.

lionel-rowe • Sep 11 '23

I agree about not including types in variable names as a general point, but in some cases there isn't much more specific you can say about them (without making them overly verbose or confusing).

But I agree with you that x and y would be fine in this case too, as sum is such a common and well-understood operation.

Maxi Contieri • Sep 11 '23

'x' and 'y' are amazing for math. not for computer science. IMHO

maximilianocontieri.com/code-smell...

Vincent A. Cicirello • Sep 11 '23

In general, I agree with you that 'x' and 'y' are almost always poor variable names. In this specific example, the sum function is quite literally a function in the math sense. You obviously went with that for the simplicity of the example. The concern @lionelrowe has is that the more descriptive addend may be too obscure for the less math-oriented, so although x is also mathy, it may be more easily understandable in this context than a technical math term like addend.

lionel-rowe • Sep 12 '23

I also frequently use variable names like x, y, a, b, etc. as params to short anonymous functions. Sometimes the variable is just super obvious from context (especially when you factor in TypeScript/intellisense). Verbose variable names are good when they help clarify, but bad when they just add noise.

const issues: Issue[] = await fetchIssues()

const criticalIssues = issues.filter((x) => x.severity === 'critical')

const issueKinds = issues.map((x) => x.kind)

const sortedIssues = issues.toSorted((a, b) => a.priority - b.priority)

Maxi Contieri • Sep 12 '23

Computer science was born from mathematics. In math, the assignment of single-letter variables (i, j, x, y) is a good practice. The concept of reference arose from the variable and many people have wondered why mathematicians can work with such short variables, while computer scientists cannot. For mathematicians, once entered into a formula, variables lose all semantics and become indistinguishable. They have a lot of naming conventions and think very carefully about their names. The difference is that mathematicians always have a fully and formally defined local context, where one letter is enough to distinguish the variables.

learning.oreilly.com/library/view/...