Let me introduce you to ...

Variable length opinions about arbitrary: things, situations and opinions (meta, right!).

0 notes

Code Poetry

I have had the chance to work with quite a few programmers and with quite a few programming languages. I have done this with the following purposes:

  • Recreational.
  • Educational.
  • Commerical.

No matter what the programming language, the purpose, how big the team is and who you are working with you must always care about the documentation of your code. This is not an official classification about code documentation, but these are the most common types I have seen and probably the most common ones:

  • /*Comments*/
  • def identifiersWithinCode(amount):
  • Documents & Diagrams
  • Doodles on a white board

/*Comments*/ or #Comments or //Comments or %Comments or <!-- Comments -->

In my humble opinion this is one of the most important types of documentations that should be done, there is no excuse not to have them. This type of documentation is (probably) like an investment, sure, it takes some time to describe what you are doing, but trust me, if you come and look back at your code in 4 months it will be most likely that you won’t remember how did you solve everything with your code. And if someone has to give maintenance to that code, this is probably the easiest way to for them to understand it. This way you will avoid having someone bugging you to explain them your code.

Sometimes you can even find bugs by just reading your comments, or in another case, someone else can find flaws.

What you should do:

//i has to run outside j, otherwise epicMatrix won't be filled with the data

//and if you don't get the value of amazingVector times the position you will

//probably get uneven values

for(i=0; i<LIMIT; i++){

    for(j=0; j<LIMIT*CONSTANT; j++){




 What you shouldn’t do:

//Print an error

printf("Error:You cannot divide by zero\n");

def thePoetryBehindMeaningfulIdentifiers(inCode):

People do not often pay attention to the importance of having meaningful names in their variables, in their functions, in their modules, in their classes, etc. Why would you even care about this? Because again you are probably not just working for yourself, people often re-use someone else’s code and when they do the last thing they want to do is read enormous amounts of code to understand how to use some API/Library. If you name your “stuff" in a meaningful way, it will be easier for others to understand your code.

But it’s not just about names, it is also about the way things are typed, different languages and even between different frameworks (within same languages), you will have different ways to type things.

The underscore: This one is in my opinion the easiest to read, though it is very uncomfortable to write, specially if you are not using an awesome text editor that will complete your function names. The first example that comes to my mind is C, specifically in GTK+, you will often see the following:

GtkWidget* gtk_button_new_with_label(const gchar *label);

The Camelcase: My personal favorite and one of the most annoying ones for some others. An example for this one is Objective-C, where a method call would probably look like this:

[someString stringByReplacingOccurrencesOfString:withString:@","];

The Creative Bastard (TCB): Again, this is no official classification, but this one seems to be the way to call it. This is no obvious way to name a function, IMHO, not the best way to name something, it probably is good for functions you use on a regular basis. An example, any of the command line tools found in UNIX, for example cd (change directory), mkdir (make directory), prstat (process status), among many others. One commercial use I have seen of TCB, is by The Mathworks Inc. current sellers and developers of MATLAB, for example:

dec2bin %convert a number from decimal to binary

tf %transference function

pzmap %pole zero map

Documents & Diagrams

This is to me the most annoying one to do, though one of the easiest ways to explain yourself (of course if you can :P). Suppose you are developing the most awesome algorithm ever to detect faces in a picture, depending on who you are, what you are doing it for, where are you doing this and why are you doing this, you will use one platform that suits you better, for this example let’s suppose it’s C++ running on a desktop. So you are writing your code but you feel the need for feedback and sure, one of your best pals has a Ph. D in Electrical Engineering and his thesis was about digital signal processing, so you ask him, but he doesn’t know anything about C++ … he probably won’t be able to help you, even with just comments on the code will probably be hard for him. The solution, a document, if you write a clear enough document explaining what your code is doing, explained with some diagrams, he is surely going to give you a hand.

Doodles on a white board

Don’t ever rely on this one, this is more of an honorific mention. The value of making a doodle of what you want to do hides behind the idea of a group of people (say the user interface design team) working together refining an idea in an accelerated and not limited way. 

Sure you might say, who ever uses white boards, you can do this with OmniGraffle, send an email and there, it’s solved. Yeah, I agree, you can but you will have to wait for everyone to catch on the mail blast, so they can all put their ideas out. That’s the biggest reason why a board rocks! Everyone can sum to the idea batch and refine the final product/prototype easily and quickly enough so that someone in the team can Omnigraffle the shit out of the doodles and add it to a document ASAFP.


Try them all, encourage your co-workers/friends to use them.

Filed under omnigraffle objective-c python c gtk matlab mathworks code programming engineering software