Friday, April 22, 2016

The most valuable tip towards writing highly legible code


As programmers/coders we all have to revisit/review/debug our own code as well as others'. Some times the code can be as large as thousands of LoC (=Lines of Code)! Large projects have a large overhead on understanding, before someone is able to add new functionality or fix a bug! Even my own projects seem somewhat incomprehensible at first, when I revisit them after a large period of time! I was always intrigued by simple solutions, but I could never form a few simple guidelines of code legibility that one could follow anywhere, anyhow, with any GUI and with any Framework!

That was before I read the recently published book "Building Maintainable Software" by Joost Visser. The title does not do the book justice. I would very much prefer the following title :
"Simple guidelines that can drive any developer to create highly legible code in any programming language!"

The book was a pleasant read. But when I finished reading it, I felt uneasy. I needed to see if the guidelines were as good as they seemed! So I gave the first principle a try. "Keep each method below the threshold of 15 LoC". And that's when the magic happened!


I had an opportunity to give this guideline a spin, on a hobby game project I was working on, which was not in Java but in gml (Game Maker's own scripting language). While reviewing my code I realized that I had more than a few methods that counted at 20-30 LoC each. And I always had a feeling of uneasiness whenever I had to add more functionality after a significant anount of development pause! So I started refactoring my code, so that each method was as short as possible (less than 15 LoC). I also tried to keep each method simple and reusable, while trying to come up with good names on my methods. There was not really much difference at first. But when I started adding more functionality to the project, I realized the following :

- Revisiting my code was as simple as reading the methods name (given that its name was a good one!)

- For those methods that had less of a good naming, revisiting its code was only a matter of seconds

- My mind seemed to work faster! I had to work with a lot of functions, but that was not really a problem in the end! Because I did not spend so much time reading and re-reading code until I could get hold of it. I was simply glancing through my methods fast! Very fast! And that was the incredible part! My initial fear that partitioning my code would create some incomprehensible code was false! Incomprehensibility does not seem to come with partitioning but with large chunks of code!

Psychologists have discovered that the human mind's working memory amounts to about seven items! So we have a buffer of seven items! The magic number 7!
Subsequently, the best tip you will probably ever get at programming is "keep your functions at about 7 LoC".

Reading the book, you will discover that there are 10 simple guidelines that will increase your code's legibility in most situations. The first 4 guidelines are generic and they can be applied on any programming language or framework :

- Limit the length of functions to 15 LoC
- Limit "if" statements per function to no more than 4
- Do not copy code. Write reusable functions
- Keep each function's arguments to no more than 4

Putting these guidelines to the test is the only way to find out if your code's legibility will increase or not. Try them out and drop a comment with the results!

Further information:
1. You can find the book here.

2. You can find a review of the book here.

3. For those of you interested in my hobby game project, it is a simple android puzzle game called "Puzzle Cats" which you can download from here. I am preparing a new version written entirely in highly maintainable code! And I am also adding PvP functionality! The new version will be released in the following months!

Tuesday, March 8, 2016

Installing screenshare on red5 server

A client of mine asked me to install screenshare on his red5 server and I found very little resources on the subject. After successfully configuring it I decided I will share the solution so that those that come after, will spend less time that I did!!!
So to the task :
I will suppose that you already have a working red5 server. My deployment was on red5-server-1.0.6-RELEASE-server.
Now download screenshare:
Go to https://github.com/deleolajide/red5-screenshare and press "Download Zip".
Inside the zip you will find a directory webapps/screenshare. Extract this screenshare directory to your red5 server's webapps folder.
Inside the screenshare you need to edit two files.
Edit the screenshare.jnlp as follows

<?xml version='1.0' encoding='utf-8'?>
<jnlp spec='1.0+' codebase='http://localhost:5080/screenshare'>
    <information>
        <title>Red5 ScreenShare</title>
        <vendor>Dele Olajide</vendor>
        <homepage>http://code.google.com/p/red5screnshare/</homepage>
        <description>Red5 ScreenShare</description>
        <description kind='short'>An Open Source Screen Share Java application for Adobe Flash using Red5</description>
        <offline-allowed/>
    </information>
    <security>
        <all-permissions/>
    </security>  
    <resources>
    <j2se version='1.6+'/>
        <jar href='screenshare.jar'/>
    </resources>
    <application-desc main-class='org.redfire.screen.ScreenShare'>
        <argument>localhost</argument>
        <argument>screenshare</argument>

        <argument>1935</argument>
        <argument>screen_share</argument> 
        <argument>flashsv2</argument>        
        <argument>10</argument>        
        <argument>1024</argument> 
        <argument>768</argument>         
    </application-desc>
</jnlp>

If you run a public server, replace localhost with your public IP.
Then edit screenviewer.html as follows (some lines are not shown since they do not contain configuration):

...
        var stream = getPageParameter('stream', 'screen_share');
        var url = getPageParameter('url', 'rtmp://localhost:1935/screenshare');
        var control = getPageParameter('control', 'true');
...

If you run a public server, replace localhost with your public IP.
And that is all.
Do not forget to add your site on java security tab or the java client will be blocked:
Then run on one PC (to share):
http://YOUR_PUBLIC_IP:5080/screenshare/screenshare.jnlp
And on the other PC (to view):
http://YOUR_PUBLIC_IP:5080/screenshare/screenviewer.html
Replace  YOUR_PUBLIC_IP with localhost to test on your pc!

P.S.
If you run a server on a public IP, do not forget to open port 1935 on your server's firewall!