'''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 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 look like a configuration/shell language. 
In six words, you make the language your own (see [domain-specific language]).

But you can obfuscate them as well. Some argue that Tcl's syntax is weird, and I can understand their complain
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 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'''

In the development cycle should be included the use of comments. It helps you to remember the ''logic'' of your program, the ''business logic'' and the references to algorithms you make use of. 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 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 he performs well regarding to this argument,
including Perl and Tcl.

----
''DISCUSSION''

Often, an easy-to-understand syntax builds a strong community, look at [Python] guys.
In my opinion, [Python]/Visual Basic users do not share the same context than [Tcl]/Scheme
users. This is a point of view that programmers that did never practice a
powerful, minimalist language like Tcl cannot understand.

Many programmers do not want their code difficult to read or to maintain, that is reasonable.
But much 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. "[everything is a string]" too.
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].
----
[[ [Category Discussion] | [Category Advocacy] ]]