Commenting and obfuscating

Purpose: Discuss programming practices related to easier or harder reading and understanding of source code written in any programming language.

Sarnold on 2006-10-28


Regardless of the language, source code might be either well or badly understood.

Yes, you can write good assembly code. Yes, you can write obscure high level code.

The contrary is also true.


Tcl programs usually look nice.

Yes, Tcl can be made to look like a configuration/shell language. In six words, you make the language your own (see domain-specific language).

But you can obfuscate it as well. Some argue that Tcl's syntax is weird, and I can understand their complaint when they come to Tcl from a C/C++/Java world.

The reason is that in order to be powerful, Tcl needs this sort of weirdness. It absolutely goes off the road, and it is the right way. (Note: I am not telling this is THE right way. It is just Tcl's way, and it is consistent.)


Whatever simple algorithm you need, there is a way to make it difficult to understand.

 proc double {var} {
     upvar 1 $var x
     set x [expr {$x*2}]
 }

Whatever complex algorithm you need, you can implement it in a clean way. (Except when complex algorithm means intensive computing or algorithmically unsolvable).

A clean way means all kinds of code quality : commenting, easy to read and to maintain, functional quality, stability.


Deliberate commenting

The development cycle should include the use of comments. It helps you to remember the logic of your program, the business logic and the references to algorithms you use. And it is not limited to these purposes.


Deliberate obfuscation

Sometimes, when you do not want other programmers to be able to maintain/modify your program, you do not comment the code. You may use obfuscation technique, combined with cryptography. Sometimes, you need to provide a source code containing business secrets (or algorithms you do not want to share) and you try to make the code as obscure as can be.

Crypto algorithms are often obfuscated, if not always.


Unwilling obfuscating

You may design a program very well in terms of modularity, and yes, that is a big win. But while designing a lot of procedures in this spirit, you think the code itself is its commenting, and leave large parts uncommented.

Six months later, you have to refresh your mind to dive into the code, and have no time to comment it. That's life.


Unwilling commenting

That is a strong argument when someone decides to use a language: a clear syntax. You write a program that seems to do exactly what you (and the client) wanted, even when you review it six months later.

Marketing people tell you: in this language, nothing is too hard to understand, everything is obvious when you read someone else's code (an often cited argument against Perl). IMHO, every single language has a domain in which it performs well regarding this argument, including Perl and Tcl.


DISCUSSION

Often, an easy to understand syntax builds a strong community. Look at the Python guys. In my opinion, Python/Visual Basic users do not share the same context as Tcl/Scheme users. This is a point of view that programmers that never practiced a powerful and minimalist language like Tcl cannot understand.

Many programmers do not want their code to be difficult to read or maintain, that is reasonable. But many of these programmers do not want to learn abstract or algorithmic concepts. You won't hear marketing people telling them This language benefits from closures, You will get tail-call recursion or In this language, everything is a string.

Advanced programming concepts solve real problems. So does "everything is a string". This is the reason why you can read things like "Scheme is the most powerful programming language".

That's not sad, anyway. Tcl' strengths are unique. Its community is open-minded. Tcllib and Tk are great.

-- 2006-10-28 Sarnold


See Tcl Style Guide, Comparing Tcl with Python.