Using a library is by itself a privilege. These days we have libraries for pretty much every complex task in software development. However, each time we use another library it is also a new opportunity to improve your understanding of software.

Most developers will approach a library by trying to figure out as quickly as possible how it is used. Frequently, they will not even read the documentation, and jump directly to writing code that uses the library.

Everyone knows that time is important for developers, and it would be difficult to understand every detail of hundreds of libraries we are required to use daily. However, it is important to consider that learning the inner workings of a library can represent the difference between writing poor programs and really grasping what you’re doing.

Using Libraries Effectively

Don’t just try to use a library. Also try to know what it is doing internally if possible. There are several ways to learn what a library does:

Most libraries, even proprietary ones, will ship with source code. This is common because it may allow third parties to do their own customizations. In the worst case, every decent library will have some documentation of what it is supposed to do and how it does it. Spend some reading time and that may save you lots of hours in debugging and design-related issues.

If you have a problem that is not discussed in the documentation, just take a look at the code if possible. Sometimes it is simpler to answer a question by directly going to the code than by reading a large manual. Sometimes, finding the answer by reading the code is easier than you think.

If the library is open sourced, then reading the code may be your only option. Many open source projects don’t have enough resources to create professional documentation. You should be able to answer yourself a lot of questions by looking at how the software is written. Maybe you won’t understand the details, but at lest the high level workings of the library should be easy to pick.

It is a fact that most libraries these days are available from an open source repository, such as github or sf.net. If that is the case, an easy way to figure out what the software is doing is just to browse the repository.

Another reason to familiarize yourself with a library is that this can give you better ideas of how to apply it. For example, there might be use cases that are not explicit from the documentation but that could be nonetheless useful.

It is also possible that, after looking at how something is done, you decide just do it yourself instead of using a library. Libraries have to be general when solving problems, but that may be just slowing down your application for no reason. It is important to have the freedom to solve such issues when needed.

Conclusion

Avoid using a library blindly, without given it at least a few minutes to understand what is going inside it. There are several opportunities for learning when working with other people’s source code.

Eventually, this kind of practice can help you in other levels. For example, you can even become a contributor for an open source library of your liking after you get more familiar with its source code.

Further Reading

A great book that discusses the use of software libraries in social contexts is “Social Software in Libraries: Building Collaboration, Communication, and Community Online“, by M. Farkas.

Mathematical functions are a simple transformation from inputs to outputs. Given a set of parameters, a function performs a transformation based on these parameters, and returns the desired results. Because of their simple character, mathematical functions are a good analogy for what can be done by a computer. Since they are independent entities, functions can be used anywhere, whatever the context is. For example, one can use the sine function to calculate the sine of any angle, no matter where the angle occurs.

Functions in programming languages are usually not so nice. They are frequently defined not only by their parameters but also by the environment where they occur. For example, if we define a function to return the amount of memory used by the application, it will necessarily have to search for information that is particular to the programming environment.

A more insidious problem with functions in programming languages is that they may change the environment where they run. For example, the previous function could very well change internal data structures in order to get the required memory information. The next invocation can, for example, use internal data instead of accessing the disk for this information. Whenever this happens, the function is said to have side-effects.

Using functions with side effects may lead to several problems. Many of these problems are debated by researchers on functional programming theory. But the main practical problem is that it is hard to understand such a function in isolation, because it may change other parts of the program. As a result, one needs to consider the program as a whole when checking the validity of a function with side-effects, instead of just looking at its definition.

Object oriented programs make this process a little simpler, because, if properly used, methods can only modify data that is part of the object. But still the issue remains, especially when programmers are not careful about how objects are manipulated.

Functional Programming to the Rescue

Functions that follow the mathematical model are said to be pure functions. There are whole programming languages, such as Haskel and F#, that have been developed in order to explore programming with pure functions. While most people don’t work with functional languages, we can still benefit by using a functional-oriented style.

One of the rules used to approximate the functional style is to avoid side effects in programs as much as possible. One can not always do this, but the general strategy consists of dividing functions into two classes: the ones with side effect and the ones with no side effects. The principle is that each method or function should have only one of these purposes.

The simplest example are getters and setters. A getter is a function without side effects because it just returns the value of something inside the first object. On the other hand, setters are free to make lasting changes to the environment. From this point of view, we see that making this separation is good not only for style reasons. It helps a lot when we known that our functions are classified by their use.

The next step is to minimize the number of functions with side-effects. By doing so, it becomes easier to understand how a program works: one can look only at the current function or method to have an idea of what is going on. It is also easier to test functions that have no side effects, because they can be tested in isolation from the rest of the program.

Finally, a program written in this style is easier to change. Functions and methods in such programs have only local effects. Thus, if something needs to be changed, we need to look only at the inputs and outputs of each function, not to the whole program.

Summary

By understanding the difference between functions with side effects and pure functions we can develop a more systematic way to create software that is easier to test and change.

Although there are whole languages that use functional programming as its main style, we don’t need to use functional languages to benefit from the idea. Separating functions between pure function and function with side-effects we can capture many of the advantages of functional programming, while keeping with whatever language we are using for the current project.

Further Reading

There are several books about functional programming the ones I like most are:

• Introduction to Functional Programming Using Haskell – If you really want to learn a functional language.
• Pearls of Functional Algorithm Design – This one gives you a deep understanding of the practical use of functional programming.

Hyperlinks are a powerful feature provided by web browsers. The original technologies designed for web promoted hyperlinks as the central mechanism for connecting pages in different sites. The concept of hyperlink is so important that it is central to the classifications used by search engines, such as Google with its page rank. Nonetheless, hyperlinks are badly misused, specially in the context of web essays, news, and blog posts.

A common idea among bloggers is that good writing for the web should be based on hyperlinks. As a result, they try to add as much hyperlinks to a web page as possible. This is sometimes used to give context to an argument, other times to provide further references.

Frequently, however, hyperlinks are misused. While hyperlinks are a good tool in many situations, I believe that in many of these cases web writers are providing a disservice for their readers.

Writing based on links is usually bad

The typical web post is written in the following way: first spend a few minutes looking for an idea, then spend one hour locating articles related to the idea, and finally spend a few minutes explaining what you think, with a good dosage of links to all the referenced posts.

This might seem as a balanced way of writing, but in reality is breaking any possibility of novel thinking. Just be sincere: unless a blogger is an expert writer and and able to spend a lot of time thinking about what has been publisher, they are just bound to reproduce bits of disconnected ideas when attempting to put together a post in this way.

In fact, I have seem thousands of web posts like this, and they don’t do anything other than requiring readers sped lots of time looking for these disconnected ideas. And I suspect that such posts are popular exactly because of this. They work as a starting point, or summary, for lots of other web sites. The typical reader will then likely bookmark or pass along this article, because subconsciously they think there is a lot of substance in it. In fact what is there is just a bunch of Google searches connected by a few words to make the whole thing work.

Hyperlinks break the flow of thought

If you provide a link, you are creating another dimension on your writing. It is similar to adding a footnote to a document. It will serve as an invitation readers to visit the footnote and get some of that new dimension.

Hyperlinks are an excellent idea when you want to promote these extra dimensions. Typical examples are technical documents, summaries, and software manuals. These are places where additional information for a specific term is welcome.

On the other hand, if you’re trying to make a point, the extra dimension is useless, because it breaks the flow of your argument. Even if it provides support, you probably don’t want people to stop reading at the moment you provide the first evidence for your ideas, correct? Similarly, it doesn’t make sense to have a link to a random page that is just related to what you’re writing.

Giving one more oportunity for readers to stop thinking

This is related to the previous reason, but has more to do with the realities of reading in a screen. There are already plenty of reasons for a reader to move to do something else in a computer. Why giving another one? If you provide a link in the middle of your sentence, you just gave an invitation for readers to leave your article, returning who knows when.

The main reason you should think about this is not that you don’t want to “share” your readers, but that you want to make a point. I guess the is also the reason you are writting an article, right?

Hyperlinks usually don’t provide what is promissed

More often than not, links are provided as a kind of service for readers, thus the implicit idea that it is good to provide them. The result, however, is usually not as good as you imagine.

For example, it is not uncommon to see pages where an author just provides links to a web searches for a topic. This is a loss of time for both the writer and the reader. Everyone knows how to do a web search, we don’t need another link with this “functionality”.

Many links point readers to generic web pages about a topic. For example, why providing a link to a wikipedia page on a subject? Like in the previous case, anyone knows how to search wikipedia. And, in most cases, the web search will bring the wikipedia page as one of the most relevant items. So, the reality of web links is that they don’t give what you want in most of the cases. Why trying to add them when they are not necessary?

Links make your document dated

A page full of links is also one that will quickly become outdated, full of unreachable and dead links in a few months. Why would you like this to happen?

Instead of providing links in the traditional way, there are some options that you can pursue:

• Don’t provide links unless you need to. For example, if I talk about the New York Times, I think it is a pretty good assumption that I don’t need to give a link. Anyone knows the URL or can use a search engine to find out.
• Provide information that can be used in a web search instead: for example, name of the author and title of the web page is all one needs to find something with a search engine. This is a more robust way to provide a reference, because the address of most web sites will change over time. Search engines make it convenient to find content even when its address changes.
• Provide links only at the end of a document: there are several legitimate reasons to provide a link. I think they can just be added to the end of a page, without any real inconvenience. Scientific papers have used this style for a long time and it makes sense in the web too. For example, I can’t count the number of times I searched a web page for a link that I couldn’t find easily. If the links were all listed in the bottom of the page it would be much easier to find them in the first place. For first time readers, it is not that difficult either. In fact it is good that they have to make the concious decision to scroll to the end of the page, because they will do so only when they feel there is a reason to get that additional information.

Summary

When not used well, hyperlinks may become a hindrance to understanding. A blog post is often a short essay, and would benefit from following these guidelines.

On the other hand when used propertly, links are a powerful tool. There are many places where links are welcome, and technical documentation is one of them. It is better to learn how to use hyperlinks properly, and make life easier for everyone.