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> // 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'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 "Nazi-like" and some have even made hard stances against putting comments in production code, at all. It'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'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've mitigated problems we've already stumbled on.<p>(edit: I removed a bunch of ranty prose like "What year is it")
Strongly disagree but upvoted for the conviction of your delivery. :)<p>Writing robust programs relies on unquestionable understanding of the logic. The specific variable and argument names are neither here nor there.<p>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.<p>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.<p>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.
Google gets rid of this problem (either extremes) by formalizing style guides for the different coding languages people use in its organization. Checkout <a href="https://google.github.io/styleguide/" rel="nofollow">https://google.github.io/styleguide/</a>