self_documenting_software

Self Documenting Software

Consider the two code fragments below.
- Which is easier to read at a glance?
- Which will be easier for the developer to read and understand six months or two years from now?
- Which will be easier for another developer unfamiliar with this code to understand?

---

Code Fragment A

    DECLARE @D_ACT [DATETIME] = 
        DATEADD(DAY, -1, CAST(CONVERT(NVARCHAR(30), CURRENT_TIMESTAMP, 126) AS DATE));
    SELECT A.MN, A.ACT, B.DYS 
    FROM DBO.AJAX_CUST_ACT_ACTUAL AS A 
    JOIN DBO.MN_TOT_DAYS AS B
    WHERE @D_ACT > CAST(CONVERT(NVARCHAR(30), B.DT, 126) AS DATE);

    GO

---

Code Fragment B

    declare @yesterday [datetime] = dateadd(day, -1, current_timestamp);
    select 
        [actual_sales].[month], 
        [actual_sales].[total_sales],
        [sales_days_per_month].[number_of_sales_days]
    from [ajax].[actual_sales] as [actual_sales]
    join [ajax].[sales_days_per_month] as [sales_days_per_month]
    where [sales_days_per_month].[sales_date] < @yesterday;

    go

---

The mental exercise I use is to ask myself, if I were to show my code to a non-programmer, perhaps the human resources manager, and ask her to explain to me what that code was doing, would she be able to do it? If an actual human (no, not the blow up kind and not the software kind but the real actual, smelly, organic, human kind) were to read your code, would that actual human be able to understand what you had written? Only after I have written my code to the point where it will pass that test to the best of my ability will I go in and add "/ /" or "--" comments. Many programmers will sneer at or speak contemptuously at this practice. My contention is that they do this because they simply aren't skilled enough to write software like this.

This type of programming is not easy. What is easy is to fall into the well of our own experience and write software that makes sense to us at this moment, but looks like scrambled nonsense to others. Ever time I write code I find myself struggling to meet my own standards in this manner, but then as I often say; if we have no objectives, we will never meet them; and if we have no principles, it won't matter if we do.

Software that is easy to read is also easy to maintain. Whether it is the original author a few months down the road or a completely different developer years from when it went into production, easy to read software is more readily maintained, with vulnerabilities and errors found and readily. It is more readily extended to include new functionality as the existing functionality is easier to understand. It is more easily tested as tests are easier to write for objects which can be readily understood. It is more likely to be reused as clearly written sections of code can be lifted off as boilerplate for other applications, and clearly defined components can be adapted to other systems more easily.

---

copyright Katherine Elizabeth Lightsey 1959-2013 (aka; my life)

Everything that irritates us about others can lead us to an understanding of ourselves. - Carl Jung