Unsolved code verbosity severely bugs my ADD and OCD
-
@Kent-Dorfman I don't see how writing inline comments instead of using meaningfull names is better? This approach does not reduce the amount of text you have to write. So, why not use meaningfull names to make the code readable and reduce the need to write comments which explain the code?
-
@JoeCFD said in code verbosity severely bugs my ADD and OCD:
Simply it is easier to find the missing curly bracket if one of them is forgot. I made this in the coding standard of the company.
is that a "recent" change? Because modern IDE's are excellent at discovering missing brackets and notifying you where you have to add them and even add the closing one automatically for you. So creating and finding missing brackets became mostly a thing of the past.
I'm with @Kent-Dorfman on this, I prefer opening brackets to be inline.
I also inlineinline
functions, getters and such.
On the other hand, I ALWAYS bracket my if body, even if it only 1 line. I'm sure Kent will disagree with me an this one ;) -
In Fortran you were forced to use short names (at least for subroutines/functions, but I believe also for variables). What added to the problem was the character limit per line coming from the use of punch cards. (Also, you could reduce the number of cards to carry around significantly by using shorter names.)
I have to work with old FORTRAN 77 source code occasionally. It is really hard to keep track of variable names inside subroutines of more than 1000 lines. Initially, most variables' intentions were commented. But, this strict discipline did not carry over into the new century. Not all variable names are commented. And also not all comments are correct.
@Kent-Dorfman wrote:
If you want to be verbose then do it in comments, not code...code does NOT replace proper use of inline commenting.
I'd say there is no proper use of inline commenting. Everything you have in code instead of comments needs to be kept up to date for it to compile. There is nothing forcing you to keep comments updated. Self-documenting code is much more helpful than comments. This does not mean that you should never write comments, but if you use them rarely people will know that they are important and need to be followed and updated if the code changes. I also don't like variable names which are too long, but I do hate names that are too short much more. The only exception is when names are used in short sections of code (e.g. variables named
tmp
to make it clear that they are used locally), as well asi
,j
, etc. for loops,ui
in Qt for the UI object generated by Qt Designer files, and the like. My collegue particularly likes copy&paste and will happily use long names as he will never type them. I am a fast typer and don't mind using longer names (and then there's also auto complete...). In large software you will read your own code a lot more often than you write it. Then it makes sense to make your code comprehensible, i.e. sufficiently verbose. (Though I advocate to make it not any more verbose than necessary.) -
@J-Hilk
To throw my own (doubtless-controversial) hat into the ring, I am a semi- @Kent-Dorfman :)I am a no-parentheses-around-single-statement programmer (
if
s,while
s,for
s, etc.). I just don't like a{
at the end of the line and the "wasted" line used for the closing}
after single-statements.OTOH, when multi-statement I always put the opening
{
on its own line below (yes, that could also count as a "wasted" line!). This has nothing to do what what IDEs can do in the way of showing parenthesised-pairs. Rather it is an aid I prefer when running my eyes down the code screen visually.But apparently unlike what he is saying I do try to pick meaningful names. I don't make them as-long-as-an-essay, but meaningful variable & function names avoid the need for many comments one might otherwise feel the need to put in. FWIW I am now trying to move away from end-of-line comments, preferring to put them on their own lines above the line they apply to.
On a separate but related note, I hate the way Python uses indentation for semantics, and then people paste their code (e.g. in this forum) without making the effort to Code-tag it, and then we can't see the indentation and they think that is fine...!
-
@J-Hilk said in code verbosity severely bugs my ADD and OCD:
So creating and finding missing brackets became mostly a thing of the past.
That depends on the age of the code. Some of our really old code has many nested conditionals and loops over several 1000 lines. The compiler might complain that the number of braces is not correct, but it couldn't certainly know on which level it is placed correctly. You still have to figure that out by hand. Highlighting of matching braces helps a little. But you still have to make sure that the highlighted brace is the correct one.
-
@Kent-Dorfman said in code verbosity severely bugs my ADD and OCD:
coding was once a creative art form where you tried to accomplish the most correct and the most elegant with the least effort...My how times have changed.
Oh, don't be an old fart now. It still can be and it is, sometimes. Also I don't see how comments replace identifier style/notation, the two things are complementary, not contradictory. I will admit that the "self-documenting code" crap's real, but crypto-ing your identifiers certainly ain't the solution to it.
I would then argue that the minions of mediocity have done well in convincing people to to think as marketers/writers intead of as engineers/mathematicians/scientists.
Don't get me started on 'scientists' ... I have to dig up theses pieces of endless
common
blocks in them scientific codes sometime ...@SimonSchroeder said in code verbosity severely bugs my ADD and OCD:
I'd say there is no proper use of inline commenting.
Then I'd say you're dead wrong, and if the folk writing the fortran code you'd been reading were not of the same mentality you may've had an easier time. Code carries meaning beside the obvious language semantics. Example to illlustrate (real code snippet):
// According to Le Chatelier’s principle, mechanical stability requires \bar{n}^{min}_{i} \geq \bar{n}^{max}. // Since this constraint must be fulfilled irrespective of the small lattice correction, we thus obtain // \bar{A}Z − \bar{Z}A \geq 0. // 10.1103/PhysRevC.94.065802 int denominator = (Z1 * A2 - Z2 * A1); if (!denominator) throw std::runtime_error("Z1 * A2 - Z2 * A1 must be greater than zero");
It's not enough that you're not dividing by zero, it must be made clear why this condition may happen, how one may deal with it (or not deal with it), and what it means when it does happen.
-
@kshegunov
Are you saying the comment block you show, on its own lines, is "inline commenting"? I took that to mean what it says: a comment on a line of codeif (abc / def) // `def` should not be zero
(which is what I said I am choosing to deprecate).
-
@JonB said in code verbosity severely bugs my ADD and OCD:
Are you saying the comment block you show, on its own lines, is "inline commenting"?
Well, yeah, it's in a function and "documents" just the
if(!denominator)
, so I count it as "inline".I took that to mean what it says: a comment on a line of code
Even so, the problem isn't the way you choose to comment (single line or in between), but rather what you comment on. If you write obvious comments that are apparent from the code then you're using it wrong(ly). ;)
-
@J-Hilk It is an old habit and has kept for today. I also use bracket for if else and for loop even when there is one line. Once one of my co-workers wrote a for loop witout brackets and added one more line outside the for loop which should be in the for loop. He spent a lot of time to find it and I helped fix it. Since then, I always use bracket for if/else and for loop.
-
@Kent-Dorfman People have different preferences. Nothing wrong with it. Do what you enjoy the most. I follow certain rules purely out of experience.
-
@Kent-Dorfman said in code verbosity severely bugs my ADD and OCD:
If you want to be verbose then do it in comments, not code...code does NOT replace proper use of inline commenting.
I completely disagree with this statement. Verbose comments can easily get out of sync with actual code and become harmful rather than helpful. Good code should be as much self-documenting as it's possible. Of course, 30+ character variable or type name doesn't say anything good about code, if it's not possible to come up with shorter name it likely means that this variable or type does too much things and should be refactored.