Writing good (no) comments

Have you ever wrote something to someone else read? Of course you did! We are always writing something to someone, even for ourselves. And this is how I want to start defending my idea: write a piece of software is just like write a simple text, an article, a paper or even a book. You write it, and you write it clear, so anyone (even yourself) can read it later.

Let’s see an example of that. Suppose your are writing an e-mail to a friend of yours. Do you write a comment about what you wrote? Let me show you:

“Dear ‘Friend of Mine’, how are you? Have you started reading that book? (comment: I’m talking about the book of John Doe). I have just finished the reading of that other book (comment: I’m talking about Alice Cooper book) and I’m wondering if I can go there (comment: your house) and get another book.“

Will your friend understand what you wrote? Probably yes! But, is it a good reading? Can you read smoothly? Probably not! Why can’t you put all the information, that are in the form of comments, inside the text itself? Let’s see how it could be:

“Dear ‘Friend of Mine’, how are you? Have you started reading John Doe’s book? I have just finished the reading of the Alice Cooper one. And I was wondering if I can go to your house and get another one.”

If you are reading this blog you are probably a developer! And if yes, you have also started to get what I’m trying to say here. Writing software is just like writing a piece of text, the only difference is that your are writing instructions, but you are writing it in a different language.

There is also a problem, most of us write code in a way that is enough for the computer to understand. If it compiles, than the computer will understand and the code is OK. That’s not true! Because the computer is not the only one that is going to read that “text”. If your software is not dead, you will read the source code later, other developers will, and even good testers will probably want to read it too.

I like a sentence that I’ve read in uncle Bob’s book, Clean Code, that says:

“The proper use of comments is to compensate for our failure to express ourself in code.”

He means that if we need to write some comment on our code to explain what we are doing, it means that we are not skilled enough, on the language we are using, to express ourselves. Read uncle Bob’s book awoke me to care about my code. But getting this point of view, about self expression on source code, was the most valuable jewel I’ve found on it.

I can’t dive into all the bad things about writing comments, that would be a “copy” of his book. So I prefer to encourage you to read the entire book, specially the chapter 4.

I also wanna close this post citing Steve McConnell:

"Good code is its own best documentation. As you're about to add a comment, ask yourself, 'How can I improve the code so that this comment isn't needed?'"

How far goes the systems optimization?

One field of computer that gained a lot of strength is the ubiquitous computing, it supports the theory of provide processing capacity to things that we use every day like microwave ovens, smartphones, tablets and other equipaments . Therefore, the industry is producing many devices with low-cost processors called microcontrollers, able to realize tasks even more complex.

Most of these foregoing equipaments works with batteries, because of that,they have a limmited capacity of power supply. Considering this limitation, the scientific community have researched much to optimize the software execution in these devices in order to consume a smaller amount of energy without affect much of their performance. In this post we intend to argue on some techniques to do it.

Some preliminary studies focus on low power consumption by systems, were based on a technique that scaling voltage and frequency during software execution. Furthermore, this technique selects the mode of work of the system as a whole without considering the device status. This technique, called DPM, is based on the principle that CPU power consumption decreases with the cube of voltage while frequencies scale linearly with voltage.

From this initial idea, emerged other frameworks[1][2] that began considering the devices status and workload of them as well as to realize an analysis of the energy consumed by the modules and identifying the points of the system that consume more energy. Therefore the system designer can refactoring the software to use the foregoing parts only when they are really necessary. As an example, we can cite the smartphones that are sold nowadays, they can detect when the remaining charge of the battery is low and in this case reduce the luminosity of the display and the use of network resources.

Another line of studies supports the refactoring and optimization of source code in order to execute all the system in SRAM of the device. This type of memory, as we know, has an extremely fast access to data and consumes less energy than DRAM memories that are usually used in desktop computers.

This text is only one general view about some researches realized to build systems with low power consumption. At the end, writing good code is not just a manner of maintainability, but also power saving that enables ubiquitous computing become a reality, so dive into it.

Developers vs Testers... Fight!!!

This text is a review of the one posted on Bytes Don't Bite.

Should people, who work with software testing, have development skills? The business knowledge is necessary for professionals in the testing area, but understanding about the structure of what is tested, which is primarily a software, is also important.

James Whittaker, who worked at Microsoft on testing and currently works at Google, wrote a book that demonstrates some techniques to "break" a software. The displayed faults are interesting, and likely to be achieved in black-box approach. The book demonstrates failures that can be caused by the user interface or through other software. Whittaker also says that many developers have difficulty to understand the environment in which the software works.

In the experience I had with software testing until now, I had the opportunity to work with several kind of testers that only interact with buttons, or other visual components, which are offered through specifications. Such testers disregarded file system, external components, operating system, network, relationship with other features, etc..

With this post, I want to encourage a fight.

Software testers, you must learn where the developers leave the bugs. Believe me, most of the failures of software are in the code! Consider different ways to find the problems. Understand the operating system, examine the software source code, understand networks, study the shortcomings of the used frameworks, study how to verify the security of the product (do not use the excuse that security is a non-functional requirement), consider all that is valid to ensure software quality.

Developers, will you let the testers break your code? See what these testers can do with the code produced by you! Approach to the thought of the testers, see how they act. Develop a critical thinking. Work hard to not let common flaws happen. Study where the bugs appear, to be able to avoid them!

At the end, this healthy dispute, between preventing and find bugs, is a way to get a software with quality and a team in continuous evolution.

Microsoft Source Analysis for C#

Unless you are already used to (and we hardly do), one of the hardest things when writing code is to maintain it well documented and well formatted to everyone (even to ourselves) understand what is writing.

Computers cannot review our source code, yet! Thinking on that, a Microsoft employee developed a tool called StyleCop, that, although not used by everyone within the company, has greatly helped lots of teams to maintain their code well organized.

Here you can find the history of the tool and a short explanation on why some Microsoft employees do not follow the (about) 200 rules established by StyleCop.

The tool integrates quite well with Visual Studio allowing different configurations for each project. Downloading the SDK allows you to customize it and even write your own rules. There is also a plugin for StyleCop called StyleCop+ with lots of other rules that can be used to standardize the source code of your project.

List or IList: that is the question

On a day during a conversation at work, a question arises: Why do so many developers always refer to List<T> instead of IList<T> in C#? But a convincing answer to this question did not appear. Thus the principle to depend on abstractions and not on concrete implementations was being despised.

Apparently it was not the first time that this question appears. And it is possible to notice that most developers using List<T> instead of IList<T> had been Java programmers one day. Is this the reason?

In C# it is common to use the letter "I" at the beginning of interface names. People who have programmed in Java might be confused since List represents an interface (in Java) while LinkedList and Stack are examples of implementations. It is also important to note that in C#, LiskedList<T>, Queue<T> and Stack<T> do not implement IList<T>, because they do not provide access by index.

It became necessary to understand the generic class List<T>, and the interfaces that it implements (IEnumerable<t>, ICollection<T>, IList<T>, IEnumerable, ICollection and IList). Thus, such interfaces could be used as a reference instead of the concrete class.

With that understanding about interfaces in mind, it was necessary to make some refactoring in the code where List<T> was being used. At first, replacing at least the return of a method from IList<T> to IEnumerable<T>. With this change, some compilation errors appeared, the method Add(T) was missing. But with ICollection<T> the code worked normally. In some other cases the IEnumerable<T> met the need because it only had to scroll through the list of items returned.

Later, we found a situation that was necessary to access a specific item of the structure, which was solved using the IList<T> interface in the return. Then a AddRange(IEnumerable<T>) method of List<T> was being used, which could easily be replaced with an extension method for ICollection<T>.

But after all these the question number two came up: Were all operations being conducted in the correct place? Since the return of each method was more conscious, it was easier to notice that certain classes were doing more than they should.

At the end, the refactoring was successful, returns of all methods that were using List<T> have been replaced by an appropriate interface. With a little more research it was possible to notice that not only developers accustomed with the List interface in Java were referring to List<T> in C#, but many people use the reference to List<T> due to resources provided by the implementation. A method as AddRange(IEnumerable<T>) could be called anywhere. A tempting proposal. However, relying on abstractions makes the code to become more flexible. And relying on interfaces that only contains the necessary functionality, limited to not try to do in a class which should not be her responsibility.

Hello, World!