Author

I am Joannes Vermorel, founder at Lokad. I am also an engineer from the Corps des Mines who initially graduated from the ENS.

I have been passionate about computer science, software matters and data mining for almost two decades. (RSS - ATOM)

Meta

Entries in design (15)

Saturday
Nov112006

A few tips for source code versioning (do not drive your co-workers mad)

Source control management (SCM) is a technical matter as well as a good practice matter. Here is a small list of tips that I have found quite useful in practice.

A good commit is like a good paper:

  • It starts with an evocative title. Ok, there is no title in SCM but there are comments provided while committing. If your SCM comment is not clear, then how do you expect your co-workers to keep track of what you are doing? A good title takes time and so does a good SCM comment. Do not rush your commit omitting the SCM comment.

  • It has a clear self-contained content and focus. If you start working on many different files, you may end-up with a large commit covering many unrelated aspect of your software. Such a commit is hard to read for your coworkers because there is no focus. A lot of things are going on but nobody can really tell what did change and what did not.

  • It goes right to the point: Insignificant elements are left outside the scope of the article. Do not commit a file if the changes have no purpose whatsoever. Such situations arise easily when you've just added or removed a few blank lines.

  • The SCM comment is your title, eventually your headline, but it's definitively not the content of your paper. In particular, do not use the SCM comment to raise questions or ideas. Those elements must be handled directly in body of your commit, i.e. the committed files themselves. The SCM comments will be quickly lost in the SCM history, but the ideas/suggestions must stay until implemented or discarded.

Wednesday
Oct252006

Let's get cosmetic on C# documentation

I am gathering here just a few C# documentation cosmetic tips that I apply in my own projects. I do not pretend to have achieved any absolute truth or any optimal practice with those tips. I just find them convenient when applied with consistency.

  • #region #endregion directives can be great, but caution not to overuse them by putting a dozen of directives within a 200-lines long code file. Indeed, if region makes the code structure more apparent, region also makes the code less proofreadable because you have to open the regions to actually start reading. As a rule of thumb, region directives should only be used for at least 100 lines.

  • XML documentation is great too. But again, Visual Studio makes it quite easy to overuse XML documentation. Basically, with 3 strokes you can generate up to a dozen of lines of empty comments. Yet, if those comments are not completed with insightful content then you're just polluting your code. Here, I define insightful as being any comment that goes beyond the information implicitly provided by the method signature itself. Example: if you have a method named Foo.DeleteUser(Guid userId) do not tell me, that userId is the user identifier. I know it because it's obvious. Tell me what happen when no such user exists. Documentation has to be maintained like the rest of the source code. Useless documentation only makes the code harder to maintain.

  • In the case of the internal project, wrapper methods (methods that basically forward the call to another method) is the kind of objects where it's actually better not to document. Instead, I prefer using a <seealso/> XML documentation reference. Indeed, documenting a wrapper is pretty much like duplicating your documentation. If this documentation is exposed to your customers, then you do not have much choice, you have to duplicate the docs (MSDN are full of replicates), but for the internal development needs, I found such replication far from being cost-effective. Thus I avoid the docs replication through XML references.
Thursday
Oct122006

Finally, I am going to be a theology teacher

According to Jeff Atwood (Coding Horror), software development is a religion. Wow, frankly I hope not, because I am quite ignorant when it comes to theological matters. A major issue with human/social studies and practices is that it is so hard to get close to anything that would be considered as scientific knowledge and not pure erratic opinions. Yet, it's not because it's hard to produce science that it isn't worth trying.

The recipe of scientific knowledge production includes a very fundamental ingredient: reproducibility. If somebody else can't, providing enough time and efforts, reproduce what you have observed then there is no hope to produce any science. For software development, the current situation is quite troublesome. Indeed, the pace of change in software development is totally dwarfing the speed of scientific production. By the time, a scientist would be able to produce a rigorous scientific analysis of software development (5 to 10 years), the software world itself would have changed so much that the study, at the time it gets published, would be already totally obsolete.

The second factor that complicates the production of knowledge is that software engineering actors do have very strong interests to defend biased positions. Science involves publishing both positive but also negative results (see the Journal of Negative Results - Ecology and Evolutionary Biology for example). Do you think that Microsoft, Google or [insert here your favorite IT company] are really going to publish anytime soon reports explaining how and why they failed miserably while developing some particular products? From a marketing viewpoint, you need to appear brilliant no matter how bad (or good) things might be in the office.

Tuesday
Oct032006

The unteachable parts of software engineering

Having the responsibility to handle the software engineering course at the ENS in spring 2007, I have started to think about the desirable qualities that make the difference between an average developer and a brilliant one. Indeed, I can't think of a better goal for this course but to actually try to develop such qualities.

What makes a "good" software developer?

It's an obvious fact that many qualities and skills are required to make a good developer. Smart and Get things done are often cited as the top criterions to decide whether a candidate should be recruited or not.

... a passionate curiosity for software related matter ...

I would complete those two criterions with a third one that I consider to be no less important: a passionate curiosity for software-related matters. Most well-known antipatterns such as programming by permutation, golden hammering, re-inventing the wheel, ... are caused by a lack of curiosity. There is far too much to know of the subject of software engineering to trust any particular school diploma (or certification) to be sufficient to produce even a "passable" developer.

Additionally, the software world is fast-paced. Hardware and software get obsolete alike. Development methods evolve. Better tools are released continuously. The sheer (intellectual) complexity of those evolutions is beyond what a single individual can possibly handle. Curiosity when leveraged through teamwork is a strong driver to actually maintain the development practices and tools as close as possible to a state-of-the-art level.

Finally, on the long run, I do not see how it is possible to stay motivated (and therefore productive) if there is no eager interest in mastering this constant flow of evolutions.

How to train such a developer?

I have listed smart, get things done and passionate curiosity as being the top qualities for a software engineer. But this list is more than troublesome for a teacher: it's not even clear whether any of those qualities can be actually taught

Concerning the first criterion, i.e. smart, I have simply surrendered all "academic" ambitions. The course schedule is far too short; beside I have the chance of having ENS students who are already very smart (though entrance exams have already filtered out students who were not so smart). Yet, the course can them the opportunity to apply their intelligence to a large variety of fuzzy problems that are inherent to software development.

The second criterion get things done is probably the most actionable element of the three. The French education system (highly selective and highly individualistic) usually produces people that are relatively weak against this criterion, the ENS students being no exception (quite the opposite in fact). I have planned to incorporate a student software project within the course mostly to push student develop a get things done mentality .

As for the first criterion, I haven't much ambition to actually transmit a passionate curiosity the students. In this respect, my first ambition will be to avoid the issue that usually plagues software engineering courses: an overwhelming boredom. I do not think it is really possible to create curiosity ex-nihilo if people have no interest beforehand. But, assuming that students are at least somehow interested (well, if not, it's going to be tough for the students and me alike), an "expand your horizons" strategy for the course might give them materials to apply and develop their curiosities.

There are two kinds of students: those who are too weak to be taught anything and those who are so strong that the teacher is totally unnecessary.

Bottom-line: out of three main qualities to make a good developer, the ambitions associated with the software engineering course I am thinking of are pretty weak. Well, considering the importance of the subject, I still believe it's a worthy attempt (stay tuned, more on later posts ... )

Saturday
Sep232006

Antipatterns of Software engineering courses

I am very honored to be in charge of the Sofware engineering and distributed applications course at the Ecole normale superieure (ENS). This will be my first official teaching assignment, and I will be affected to brilliant Licence 3 students (it's pretty tough to get through the entrance exam of the ENS).

Software engineering is a difficult topic to teach. I have been browsing the web just to have an outlook at what people are usually doing in a software engineering course, and I must confess that I haven't found anything very satisfying so far (although the MIT experience is definitively worth reading). In a nutshell, I would say that software engineering is the art of producing great software with limited resources. In respect to this definition, it seems that there are many ways to spend hours teaching things that totally miss the point. I have listed in this post what I think to be the 3 most common ways of disgusting students from all software engineering matters.

Coding antipattern

Here is the 300-pages API. This API will be the subject of your exam. Documents will not be authorized.

The second fastest way on earth to get your 30h of teaching ready is simply to teach some particular programming language and its associated technologies (think Apache/PHP/MySql, stay tuned the fastest way will be detailed next). Just take any reference documentation, and you get enough material to talk for 30h. But your course is both deadly boring and super-short-lived. Some people assume that their students have no prior knowledge about any language. I won't (it's stated in the course-prerequisite btw). My objective is not to teach the syntax of any programming language, because I believe students are smart enough to learn that by themselves. If not then, I would say that it was a bad move to take the software engineering course in the first place.

ISO-certified development antipattern

If you don't assess your customer requirements through a 17-phase process, then you're not ISO-171717.

Just by looking at Learning Tree - Software Engineering course (one of the top result of Google for "software engineering"), I think Wow, those people are attempting to kill their attendants with boredom. Look at the table of content: Life cycle phase contains (sic) 1) Understanding the problem 2) Developing the solution 3) Verifying the product 4) Maintaining the system. I can't remember of any software project that ever happened that way but who cares because the content is going to be nothing more than obvious statements anyway.

I call this kind of teaching ISO-certified development, the worst part being certainly the enumeration of software life-cycle models (which are, according to Learning Tree: Waterfall, V, Phased, Evolutionary and Spiral). This approach is basically the extreme opposite of the coding course. You're not teaching anything technical, instead you end-up with long, super-detailed, over-boring descriptions of business practices that do not even exists as such in the real world anyway.

Green-field projects antipattern

Our project was to develop a video game. Alice wrote the scenario, Bob took care of the rules and I did the graphics. The rest has been left unfinished.

The fastest way on earth to get your 30h software teaching course ready is the green-field project: just say Decide among yourselves what you're gonna do, I will be the judge of the software you produced and then, spend the next 30h doing groupwork (groupwork is like teamwork but instead of having a team, you have a random bunch of people, i.e. a group). Don't take me wrong, I think that projects do have a huge pedagogic value, yet the probability of re-discovering good software engineering ideas just by doing random groupwork is low.

There are also other criticisms to the green-field projects as usually practiced. The first poor practice is to let the students come up with their own project ideas. For various reasons, students have a tendency to favor projects that are quite ill-adapted (such as video games); then it's really hard to scale the project in such a way that it matches the time to be invested in the course. The second poor practice is to let the students come up with their own internal organization. I have never encountered any company where all employees are equal, I do not see why it should be the case in a student software project (more on the subject in a subsequent post).