1. May, 2012
One would think that “open source” is all about sharing. But that’s a misconception. Example: Try to use some GPL‘d code in your non-GPL OSS project. Oh, the humanity.
So called “proprietary” software at least believes in “buying love”. They won’t show you the source but for a price, you can at least use their work without many questions asked.
OSS is different. If you use the wrong license, you must be a moron (proof: You’re using a different license than me. QED) Nobody wants to share their hard work with morons!
Especially not since the process to select the “perfect” OSS license is so painful. You need to read legalese, try to understand it, reason with the nice smiling person on the other side of the padded wall (a.k.a “outside”) that you’re not insane – the rest of the world is and you can prove it.
Ever tried to get some OSS project to share their code under second license? It’s a lot of fun – unless you’re serious. Then … it’s not so much fun.
Why I’m ranting?
I spend a lot of time on stackoverflow. It’s cool. It’s full of source.
But can you use any piece of that source code in your OSS project?
Are you sure?
You are. Splendid. Do you really think a lawyer would see this the same way?
1. March, 2012
A lot of people way “you must comment your code.”
Kevlin Henney wrote an excellent piece on this topic in 97 Things Every Programmer Should Know: Comment Only What the Code Cannot Say
It really boils down to the last sentence: “Comment what the code cannot say, not simply what it does not say.”
There are various reasons why people demand comments:
- They are not fluent in the programming language or don’t know enough to read the code. There is nothing wrong with the code – the readers simply don’t know enough to understand it.
- The code is broken in some way and you need the comment to make sure people don’t break it even more.
- The comment explains something that no one will see from the code.
Only #3 is a valid reason for comments. #1 is just adding noise for people who shouldn’t touch the code anyway. #2 means you should refactor the code to make its intent clear – adding comments will only make things worse.
15. May, 2011
Documentation usually has these three attributes: It’s incomplete, outdated and plain wrong.
That doesn’t apply to every bit of information in your documentation but it you can be sure the statement above is correct for the whole documentation.
As a consumer of such documents, it’s a nice puzzler to determine into which of the three categories a bit of information belongs.
This leads to the common “we hate documentation” stance that all software developers soon adopt, no matter if they have to write/maintain the documentation or if they have to use it.
As we all know, the only reliable source of documentation are unit tests. But they can still be incomplete (= missing the example you need) or outdated (= missing examples for the latest API).
The solution? Generate documentation from the source code. And I don’t mean “from javadoc in the source code”, I mean literally from the code. If a method is used in a certain way in 317 places in your code and once in a different way, then you have two examples. One of them probably works, the other is probably documents a bug which your tests missed.
Eclipse is starting to get support for this. The first step was code completion. Now we have a couple of guys working on Eclipse Code Recommenders.
This summer, Stefan Henß starts to work on an “extended documentation platform” for Eclipse.
28. September, 2010
Software developers believe that documentation is just another way to say code is buggy. The reasoning is like this: If the code was easy to understand and/or did what you expected, then why document it?
While this is true at the level of a code line, there should be some documentation explaining your overall view of the world.
Next, we have end user documentation. End users have no idea how software works, they just know they have to get some work done. Stat. For them, good documentation can be the difference between a nice day and weeks of overtime.