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.

    Xc = ds.imgtf(tsf, sz, rm, sc)

vs

    // normalize the input images
    processedInput = inputData.processImages(customTransform, finalSize, resizeMethod, maximumScaleFactor)

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.

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.

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.

(edit: I removed a bunch of ranty prose like "What year is it")