
How much you suck as an engineer = 1/(sum(len(n) for n in Nv)/len(Nv)) - oneelectron
This is conjecture that programmers should aspire to write self-documenting and expressive code. Terse code is just poor form, in the modern programming world.<p><pre><code>    Xc = ds.imgtf(tsf, sz, rm, sc)
</code></pre>
vs<p><pre><code>    &#x2F;&#x2F; normalize the input images
    processedInput = inputData.processImages(customTransform, finalSize, resizeMethod, maximumScaleFactor)
</code></pre>
Sample1 is preferred by most people I work with, and the standard for almost anything you&#x27;ll find published in Python or Java. The web world is a little more forward on this, although still behind if you ask me.<p>I have always followed a practice of writing goals as comments first, then comments as pseudocode, and then simply adding in the syntax below that, with variable names that would be obvious at a glance. However, colleagues have found this practice &quot;Nazi-like&quot; and some have even made hard stances against putting comments in production code, at all. It&#x27;s almost a side job for my colleagues to show me that my concerns are unwarranted.<p>Is it acceptable to demand rigor in expressive naming conventions and heavy commenting within my team? I&#x27;m seeking opinions on a team guideline for erring far on the side of readability over conciseness. I argue it has tangible benefits, and would&#x27;ve mitigated problems we&#x27;ve already stumbled on.<p>(edit: I removed a bunch of ranty prose like &quot;What year is it&quot;)
======
tlack
Strongly disagree but upvoted for the conviction of your delivery. :)

Writing robust programs relies on unquestionable understanding of the logic.
The specific variable and argument names are neither here nor there.

It's almost impossible to understand program flow when code is extremely
verbose and heavily abstracted. Little comments like "add 1 to x!!" are not
only useless in practice but they are toxic to code understanding.

The code already tells you what it does. As a maintainer, I need to understand
why, and to what ultimate purpose. "tmp2 ->
temporaryFailedCustomerRecordsCounter" wastes precious space making the
obvious infantalizing.

It's ok to expect people working on your complex, important software to be
knowledgeable about the domain and its' standard terminology. I expect my Lyft
driver to have a drivers license.

~~~
oneelectron
Glad you can defend the totally opposing view well. Respect on the
'knowledgable about the domain' point.

I would argue that there is no more abundant resource than whitespace on
computers. Useless comments (usually written after the syntax is written)
definitely suck. But in a file with well written comments, you can actually
just read the comments alone and understand the code as fast as you could read
news headlines.

Another point, the only purpose of code as we know it is to serve as a human-
readable translation of machine instruction. To me, the best achievement of
that is a document that reads like natural language. After all, wouldn't it be
better if we could just describe intentions in common speak and have the
computer figure out the details? To me, well thought verbosity in code is a
step towards that.

~~~
tlack
Good points. Some rebuttals:

First, in the context of this argument, I'm talking about work in high level
languages like Python, JS, fairly expressive C++, etc. If we were coding in
assembler -- LEA, LDR, JNZ.. -- I'd definitely want a ton of low level
comments!

When I say wasting space, it's not about disk space, or shrinking your screen
size, or even formatting. It's more about what you can see all at once.

Think back to a recent time when you had a tough to fix bug. Like something
really not trivial that you beat yourself up about for a while.

I bet it involved you working through various levels of libraries, opening
them side by side or paging back and forth, trying to figure out what went
wrong in the logic.

It probably wasn't cuz you misunderstood what a variable did. We have great
ways to document that, like the function header.

Now imagine that process if it's all on the same screen. If everything feels
"tangible" to you, because each level of logic (to some reasonable point) is
visible, accessible.

When I encounter a code base with hundreds of source files in various folders
and some flimsy abstraction tying it all together, such that I can't see a
clear delineation between parts, I go nuts!

Here's a very practical example. Imagine you have some library that wraps a
remote API. Something important, like Payments. The hard part there is
understanding failures (does it retry?), edge cases (whats diff when i run a
test CC#?), stored state (can I resume this from a different part of the
code?).. those things are mighty hard to glean even from good statement-level
comments, even if I could take the time to read all 3,000 lines of code.

We need higher level great docs.

I'd love to code in English or something like it, but looking at the code on
my screen right now, those would be some really complex sentence structures.
:)

~~~
oneelectron
Definitely agree on too-many-files. Documenting architecture is a whole
'nother art that's overlooked. We diverge on locating errant code though, big
time.

You'd trip at my code in the payments example because whatever is 3000 for you
would easily be 5000 for me. Not only do I write comments before each line of
verbose syntax, but I also add blank lines after braces and between logical
"blocks" of operations.

However, that structure also gives me a mostly searchable index of every
logical block of my code. That gives me a very straightforward way to bisect
down to the problem, no matter how far away that code is linearly. It feels
like lots of little sandwiches instead of a giant sandwich, and I'm looking
for one bad slice of meat. I at least can quickly scan and jump to sandwiches
containing meat when they are so explicitly separated and annotated.

I'd also argue that since good comments (written before syntax) can be read as
their own document, I also have full coverage documentation by default. If I
wanted to produce a crazy deep documentation page, I could actually just pull
every line starting with // or /* (but really I just use Docstrings/JSDoc/etc
on top of my inline comments).

I believe I've arrived on this out of practicality. I maintain 10+ codebases
of differing platforms at any one time, and my most frequent problem in life
is arriving at a codebase and thinking "Okay, what was going on here?". My
approach now is just "read the green" (I color my comments slightly green
gray) and within minutes, I can understand the entire functionality of that
code and search for patterns I know will exist. I don't believe that's
possible in equivalent time by executing the program line by line in your
head.

------
_drimzy
Google gets rid of this problem (either extremes) by formalizing style guides
for the different coding languages people use in its organization. Checkout
[https://google.github.io/styleguide/](https://google.github.io/styleguide/)

