Kaeru's Online Journal

"You know you're brilliant, but maybe you'd like to understand what you did 2 weeks from now." -- Linus Torvalds

If you're just starting out with software development, there are some best practices you should follow. One of which is adhering to coding style guide.

There are many reasons, but the most important of all is that it makes the code easily readable. Most of the time, in professional life, you will need to read code done by others, and others have to read your code. When variable, function and class names are consistent, it makes it easier to code, and resuse code. When difficult sections, are commented, it helps you and others figure out what it's supposed to do. When it's coded for readibility, it can save time commenting, and easier to figure out.

By following good established style guides, even if your'e a novice developer, it gives a good impression to others. The code looks "nice", peers and seniors can see what you're trying to do, and can help provide advice.

A few times in my career, some people have commented on "how professional" my code looks, or incredulous, and somewhat insulting "you must have cut and pasted this from somewhere!". I'm not a good developer, but it's a lot easier for a better developer to read my code, and see, "Oh you're grabbing unique values from our main index here, it's much faster this way in SQL. That's why it's slow". By comparison, if it was messy, uncommented and slow, or buggy, a senior/fellow developer is more apt to be frustrated and comment, "No idea what you're doing, and it's slow as hell!".

It may be faster, but if it's broken down the line, you may not remember or figure out what you did, because there are no comments and you used function and variable names like wtf, sht_hpns.

Finally, the style guides often include commenting guidelines, and macros, so that auto-generated documentation can be run against the code. eg. PHPDocumentor and Javadoc

Some very large shops, tend to have internal style guides, but generally if one is not available, use the one that is recommended by the language project. Here are some:

• Linux kernel coding style for C
• K&R for C.
• Pear for PHP.
• PEP 8 for Python.
• Code Conventions for Java
• Create Maintainable Code with a CSS Styleguide

Most of these guides will also point to some settings for common editors. Or you can Google, if it's not mentioned.

There are also styleguides for documents and design. Just like their code equivalents, organizations with a good written and design styleguide, the outputs look professional.

Unfortunately in Malaysia, a lot of development shops don't insist on coding style guides (or even heard of them). If you've just started work in this situation, ask if there is one, and then suggest that the team use one. If nobody cares, find and use a commonly used one such as the above when writing your code. Then look for examples from good FOSS projects. You'll be on your way to picking up good habits that will serve you well for your career.

Most of us now work with relatively large amounts of data, whether it be media or data. I've been on a Gigabit Ethernet switch now for a few years, because transferring data or virtual machine images of several gigabytes over the network is painfully slow at 100Mb/s (12.5MB/s max). If you see this limit when transferring files with GigE equipment and Cat5e/6 cables, chances are auto-negotiation is setting a conservative limit.

One usually thinks of wired connections as relatively plug and play, and that's true for the most part. Unfortunately, I found out recently, that at least on my Ubuntu Linux workstation, with cheap networking equipment such the RealTeks, the Lantecs and what not that you have at home, the defaults may set your media speed to 100Mb/s (Fast Ethernet) and not 1000Mb/s (Gigabit Ethernet).

These days you do not need to look at blinking lights to see if stuff is connected (usually).

Settings for eth0:
    Supported ports: [ TP MII ]
    Supported link modes:   10baseT/Half 10baseT/Full
                            100baseT/Half 100baseT/Full
                            1000baseT/Half 1000baseT/Full
    Supports auto-negotiation: Yes
    Advertised link modes:  10baseT/Half 10baseT/Full
                            100baseT/Half 100baseT/Full
                            1000baseT/Half 1000baseT/Full
    Advertised auto-negotiation: Yes
    Speed: 1000Mb/s
    Duplex: Full
    Port: MII
    PHYAD: 0
    Transceiver: internal
    Auto-negotiation: on
    Supports Wake-on: pumbg
    Wake-on: g
    Current message level: 0x00000033 (51)
    Link detected: yes

sudo ethtool -s eth0 speed 1000

re1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 7200
    options=389b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,WOL_UCAST,WOL_MCAST,WOL_MAGIC>
    ether 00:13:f7:3a:80:f3
    inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255
    inet 10.1.1.1 netmask 0xffffff00 broadcast 10.1.1.255
    inet 10.1.1.2 netmask 0xffffffff broadcast 10.1.1.2
    inet 10.1.1.3 netmask 0xffffffff broadcast 10.1.1.3
    inet 10.1.1.4 netmask 0xffffffff broadcast 10.1.1.4
    inet 10.1.1.5 netmask 0xffffffff broadcast 10.1.1.5
    inet 10.1.1.6 netmask 0xffffffff broadcast 10.1.1.6
    inet 10.1.1.7 netmask 0xffffffff broadcast 10.1.1.7
    media: Ethernet autoselect (1000baseT <full-duplex>)
    status: active

I follow some aspects of Getting Things Done (GTD) and one of the most important concepts for me is having a reliable mechanism for collecting new things that need some sort of action, and then filing into appropriate systems to manage and review. I only have two review systems, Trac and Datebk on my Palm phone.

If a task is not added to one of these systems, its unlikely to be reviewed, and likely to be forgotten.

I'm generally ok with getting a tasked filed for digital collections (email/Skype etc.). Palm on a phone has greatly helped in quickly dealing with filing phone related tasks such as text messages and calls. My paper collection mechanism sadly such as mail, has been woeful. It's been one two many times, in which I've missed due dates because it's hidden in a pile of stuff (stack of papers) and not reviewed.

Being sick for most of last week, creating a system and sorting out paper was a good mindless yet productive exercise.

Inbox Tray

I organized it into three simple trays:

Top

Stuff that has not been reviewed and filed into my review systems.

Middle

Stuff that has been reviewed and filed as a task. This means that this stack of paper isn't a mindless pile of stuff. When I do my review and management of tasks I'll get to one of these in right order of priority and urgency.

Bottom

Filing and archiving. There is a low priority file or archive task attached to them, just needs to be filed to relevant folder.

Transparent folders

In the middle tray, pieces of paper often need to be grouped together. I refer to these as current project folders. Invoices with checks and receipts, contracts with amendments and so on. Transparent plastic folders are perfect for this task, as it's very easy to quickly put them in, and also see at glance what's in it (saves time on labeling). I use sticky notes within these folders for additional reference information.

When you're done with them, some like the one shown here, even have binding holes to easily file them into a proper binded folder.

Finally these plastic folders are a lot easier to deal with then binded folders when you need to pull them out and reference it quickly to take some action. You can easily pull them out of the tray, or have some sort of container within easy reach. The most important point here is that what is contained in these plastic folders and trays is not "stuff". Except for the top box, they're already organized in my trusted and often reviewed systems.