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

Facebooktwittergoogle_plusredditpinterestlinkedinmail

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.

Facebooktwittergoogle_plusredditpinterestlinkedinmail

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:

  1. It is three times as hard to build reusable components as single use components
  2. 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

Facebooktwittergoogle_plusredditpinterestlinkedinmail

Designing for security

In designing any system and especially systems with a public facing interface, security is always a concern.

Jerome and Michael in an awesome paper titled The Protection of Information in Computer Systems layout general security principles that I think would be of great help to any designer, so below is a summary of the principles.

Least Privilege

An entity in the system should have the minimum set of permissions needed to carry out the actions for which they are authorized.

This may seem intuitively obvious but a lot of applications have the ability to read or even modify privileged information. This exposes the system to a possibility of wide damage in case they are ever hacked.

Fail safe default

A users access to any particular area in the system should by default be denied unless a specific permit is given.

Guess now you know why you had to signup to use an API.

Economy of Mechanism

This again boils down to a principle we talk about frequently on this blog KISS (Keep It Simple Stupid).

All component interfaces and interactions between them should be simple enough to understand.

Complete Mediation

A system should always validate access rights when a request for a resource is made.

That is never try to cache permissions based on any parameter. However, make it easy to generate new authorization taken when need be.

Separation of Privilege

This principle states that granting of privileges should not be based on a single condition.

While this may seem counter intuitive at first think about say a bank manager who grants access to the vault. If the manager has this absolute right and he’s the only one that does, then what happens when the manager first needs access to the vault?

Least Common Mechanism

Systems working in concert should share the least amount of information needed.

This helps prevent spread of invasion from one machine to the next.

Psychological Acceptability

At the end of the day your system is useless if you protect it so much that no one is interested in using it anymore.

That is whatever security mechanisms you put in place, they should not make the resource harder to access than if the mechanisms we’re not there.

Have you used any of the above principles in the design of your own system? Talk to us.

Facebooktwittergoogle_plusredditpinterestlinkedinmail

Interface design: What to consider

As a back-end developer, the code you write is meant to be primarily consumed by other developers in writing their services. To this end, you would want to know how well written the interface is. This information will give you a sense of the adoption levels for your service.

Today we will take a quick dive into some of the measures that you can use to evaluate your interface design.

Conciseness

A concise interface enables maximum action with the smallest number of commands. To illustrate this point imagine inputting data to your program. You have the option of either

  1. Keyboard
  2. Screen Display of characters

In this example, typing in the keyboard is clearly more concise. You can get input data far more quicker.

Another way to think of the problem is by comparing programming languages

Java

public class HelloWorld
{
    public static void main (String[] args)
    {
        System.out.println("Hellold!");
    }
}

PHP

echo "Hello world";

Clearly PHP is more concise.

Expressiveness

Expressiveness describes the interface’s ability to command a wide variety of actions in its domain. This effect can be more readily seen in specialist fields. For example if you are writing code or library for AI, a specialist language like prolog maybe more suited to the task than a more general purpose language.

Prolog

likes(mary,food).
likes(mary,reading).
| ?- likes(mary,food). 
 yes.

PHP

function likes($item,$subject,$person,$database){
       return array_search($item,$database[$person][$subject])!==false; 
}
$mary=["likes"=>['food','reading']];
$people=['mary'=>$mary];
echo likes('food','likes','mary',$people);

And prolog shines for even more complex conditionals.

Ease of use

This relates to how many things a developer must know in order to use your code.

If your application has a GUI interface then this is rather low since the knowledge required can simply be summed up to point and click. However TUI applications ease of use drops significantly.

This is not to say that TUIs are bad, in a different context, say if your application is being used as a service library then a TUI interface is great for ease of use.

Transparency

This boils down to your application. It should not only be doing the right thing, but must also be seen to be doing the right thing.

You can greatly improve on transparency by providing useful feedback to the user, providing solid error management, well written error messages, intermediate results etc.

It would also help a lot if you ship your code source as well.

Discover-ability

Your application can be considered discover-able if it assists the user to master it. Comments, context sensitive assistance, Doc Blocks etc ensure that it is easy for the developer to find out what they don’t know about your application.

If a convention, best practice or standard exists for expressing or solving the particular problem, use it.

What do you normally consider when developing the interface for your service? Talk to us on the comment section below.

Facebooktwittergoogle_plusredditpinterestlinkedinmail