Blogs:PetrHejl:BeautyMatters

From APIDesign

Beauty Matters

J. Tulach in his Practical API Design book claims that beauty is not the most important requirement when you design your API. Because he is repeating this multiple times at various places I got the bad feeling that this could be easily misunderstood. While you should not sacrifice the API usability or evolution readiness to beauty you should definitely make it as beatiful as possible.

Wait, beauty is not measurable! Or is it? I think the only missing thing is the definition of beauty. Most of the terms in common language mean slightly (or completely) different things to different people. That is why many of the engineering disciplines define its own terminology, while often using words from common language but with exactly defined meaning. Can we define the beauty of the code? I believe the majority of the engineers can agree that readable and maintainable code is much more beautiful than complicated unreadable code. One of the defined metrics can be adherence (usually underestimated) to code conventions. We can took the general Java code conventions as definition or use custom ones for our project (note that almost every successful open source project has its defined code conventions). Once we have the code conventions defined we can even measure the beauty automatically with tools such as Checkstyle (PMD, FindBugs). The code conventions can be considered as a basic definition and we can define additional rules such as forbidden or required idioms which we can check later automatically. Also you usually don't want to use common anti-patterns although they might work in a particular case.

The beauty of the code is also visible as money spent on the project maintenance and bugfixing. Personally I think that programmer who refuses to conform to common rules defined for the project is missing the important ability. There is no value in spoiling the code by using individual rules or idioms making the code harder to read and maintain. Usually you could hear such programmers arguing that their rules and habits are better. I don't think so. Once you have a definition of the beauty the violation of such definition does not make any good to the project. On the other hand if the project rules are complete nonsense the programmer should either try to change them (in general) or choose the different project.

Overall the term code is a bit misleading as it is associated with CPU execution in our minds. However the source code (and programming language) is not primarily designed to be readable by machines. The purpose of the source code is to be shared by several people (not machines). So compilable and runnable code is not enough. It has to be readable and maintainable by others (growing popularity of Domain Specific Languages confirms this). Otherwise any bugfix will take longer or the maintainer will choose to rewrite the part from the scratch. Obviously not an optimal solution. What do you think about the beauty?

--PetrHejl 16:20, 10 November 2008 (UTC)

<comments/>

I think Petr is right. At least from one side. However there is more. There are at least 3SidesToEveryAPI.

--JaroslavTulach 12:24, 12 August 2010 (UTC)