July 2015 – Tech leadership

Six files to include in your next project

If you have written a software project and you would like to open source it, one of the key considerations is what to include in the projects directory.

Files included here should act as a guide for a potential user or even contributor looking forward to understanding your code.

Below are some suggestions on some standard files you can include.

Readme

If nothing else, make sure that this file is there. This will act as the overall road map to your project.

The file should preferably be in markup, this will enable github to automatically parse and display this file whenever someone lands upon it.

See https://help.github.com/articles/github-flavored-markdown/ for more.

Install

Unless your application is one of the rare birds that work straight out of the box, you probably want to provide instructions on installing and deploying the application.

This may include details such as how to pull in dependencies, where to put the project files etc. You may also include details on how to setup a dev environment if your project supports it.

Authors

Give credit where its due, consider listing everyone who helped forge the project.

Changes

This is especially useful for long living projects. In this document you can log any significant changes between the various versions of your application.

Do not assume everyone will read your commit messages or tag comments.

License

Github will usually suggest licenses for you, select one that makes most sense to your project. If you do not include a license file then your code is legally not available for modification or further reuse by other parties. I assume this was not your intention.

FAQ

Your users will run into issues while deploying, using or contributing to your code. As a preemptive measure you should consider having this file to document the most common issues and their suggested solutions. Dealing with support requests is already hard enough as it is, this simple action can cut this requests by up to half.

Before you ask, no, an issue tracker does not count as an FAQ.

News

For particularly large projects, a news document may be an important feature allowing the public to have higher level knowledge of the happenings in your application

What files do u normally include in your own open source? Tell us about it in the comment section below

Fun with RFCs

Developers and techies in general are not usually viewed as the most interesting people on the planet.

Popular culture portrays a caricature of a shy man who is comfortable only when spitting out code to a terminal interface.

This is of cos wholly misguided in fact a very important part of the process of writing an Internet Engineering Task Force (IETF) standard is the submission of a Request For Comment (RFC).

The submission process is informal by design and in addition to standards, survey results and philosophical basis for future RFCs are routinely submitted.

More interesting however is an April 1st culture of a joke RFC. While RFCs normally need to go through several stages including starting out their life as Internet-Drafts, joke RFCs don’t have to go through any of that and become instant published RFCs.

This tradition has come up with quite some gems including:

A Standard for the Transmission of IP Datagrams on Avian Carriers RFC 1149

    This memo describes an experimental method for the encapsulation of
    IP datagrams in avian carriers.  This specification is primarily
    useful in Metropolitan Area Networks.  This is an experimental, not
    recommended standard.  Distribution of this memo is unlimited.

Hyper Text Coffee Pot Control Protocol RFC 2324

    This document describes HTCPCP, a protocol for controlling,
    monitoring, and diagnosing coffee pots.

Scenic Routing for IPv6 RFC 7511

    This document specifies a new routing scheme for the current version
    of the Internet Protocol version 6 (IPv6) in the spirit of "Green
    IT", whereby packets will be routed to get as much fresh-air time as
    possible.

You can find this and the complete catalog of RFC jokes here https://en.wikipedia.org/wiki/April_Fools%27_Day_Request_for_Comments

Do you have any other RFCs or geek culture you find interesting? Share it with us on the comment section below.

Why modifying vendor code is a bad idea

Writing software for production is one of the toughest endeavors a person can take. The fact of the matter is that more than often we are tempted to simply look up an existing solution and modify its source for our own needs.

At the surface of it this seems quite desirable, maybe even a good practice, in reality going down that path is likely to take you into a world of horrors. Here is why.

Writing reusable code is hard

To fully understand this concept we must take into account the rule of three. This rule states that:

It is three times as hard to build reusable components as single use components
Reusable component should be tried out in three different applications before it will be sufficiently general to accept into a reuse library.

Now of cause this are not hard rules but they provide an easy to recall rule of thumb and its lessons are intuitively clear.

A truly general solution solves not only the general problem but also the specific solution of which it was intended to solve, as such tests for it must be written to this specification.

With this knowledge in mind how much are you willing to bet the solution you wish to modify was written as a general reusable solution?

Specific solutions exclude other solutions

With the idea that the solution your are about to modify was probably written to solve a specific solution, we must now think of the impact the design decisions made by its maintainers has on its ability to solve other problems.

As it turns out there isn’t a best design solution for a problem but rather each designer would probably land on their own unique and correct design for solving the problem at hand. This would mean to modify the existing design would need you not only to understand the problem but the philosophy on which the design solution was chosen.

In iterative methodologies (Agile, XP etc) this is especially a problem since simple designs are encouraged and over time they evolve to meet the complex needs of the final solution. The evolution process is probably not documented and maybe hard to know of its existence let alone comprehending it.

Understanding the solution

Given that we now have a specific solution it may be particularly hard to understand it without knowing the specific problem it was intended to solve. To the designers of the solution, the problem is probably painfully obvious, however to you the outsider, this is very rarely the case.

Furthermore you may find that as time went by even the original designers forgot how the solution actually works! If this phenomena sounds strange, try looking at code you wrote a couple of months ago.

Documentation

Or in our case, lack of it. While the virtues of proper documentation are preached at every corner of the software boulevard, its adherents are scarcely anywhere to be found!

If you know nothing else about the project, you can still gamble on inadequate documentation, this exacerbates all the problem mentioned above.

Even more interesting, you, the modifier of the code are not likely to document your changes either further complicating things down the road.

Later releases

Unless the project you are thinking of modifying is a dead project. The maintainers are probably fixing old bugs and adding new features all the time.

It goes without saying that this changes are likely incompatible with your own version so you may need to redo the work all over again whenever a new release comes out.

So what to do?

Reusing and modifying large components will be a problem in the foreseeable future. However some actions you can take to at least gain some benefit out of existing software include:

Reuse only software meant for reuse. An example of this would be packages and libraries
Do not modify the code, instead write an adapter to interface the package and your code
If you need to change more than 20% of the code, rewriting it is likely to be cheaper
Use a dependency manager
Always write integration tests and run them every time a vendor does a release
Whenever possible, use packages with developers of some repute

Do you have any advice on reusing code? Talk to us on the comment section below