Hey there!


Why writing verbose code is good for self documentation

I recently had an interesting discussion about modern programming languages and I also have seen some, rather weird, opinions of people who believe that being verbose in your source code is a bad thing. I will try to summarize in this post why actually being verbose is a good and useful thing.

First of all, what do I mean by being verbose? I mean to use language elements that can be, but not necessarily need to be explicitly stated in the source code.

Many languages have some implicit definitions that are always used, unless you override them. For example in c# these both lines are identical:

Because every function, if not stated otherwise is private be default. There is no need to use keyword “private”. But well, you can still do that. Why? Because not everybody knows it and that doesn’t necessarily mean that person is a newbie (there are people who simply work in so many languages that they are occasionally unclear about things like this), and even if they were, what is so wrong on writing a source code that is simple to read even by newbies? So in simple words this will make it extra clear that a function is really private. It doesn’t harm anything and may be useful to some people who are reading the code.

The other thing which I noticed, is that people usually do not like to use “this” in c++. I am personally using “this” everywhere I can, in every function, just to make it 100% clear that this variable or a function is a non-static member of instance of class in which the function body is defined. It’s not for me, it’s for people who are reading my code, so that they don’t need to scroll potentially hundreds lines of code just to figure out whether variable, which they are looking at is function local or belongs to the class. I know that some IDE’s are showing these in different color, so that their scope is pretty clear, but these people may be reading this code in VI, or notepad. Again, it doesn’t harm anything, there is no difference in binary produced by compiler. In addition, it helps to ensure that your call will not conflict with some other function with same name.

It doesn’t improve the code, it doesn’t make it better nor worse. It just makes it easier to read (not by you, but by someone who doesn’t know the code and wants to understand it).

And what I hate most are languages which doesn’t require explicit type defintion, but are still strong-typed, like python (yes you probably already know I hate python :-)). These languages makes it super hard to figure out which datatype you are looking at, unless you attempt to debug it in some way.

This may be good for obfuscation, but seriously, what’s the real benefit of programming language that allows you to write shortest possible source code in number of characters which is totally unclear and hard to understand? To save space on hard drive? I don’t think so…