Food Chain and Food Web (Ecosystem) EVS, B. Pharmacy 1st Year, Sem-II
Importance of Documentation for programmers
1. Documentation in programming
The Independence Day began in the most thought provoking way for the members of
Kolkata IT Professionals group. Yet another pertinent issue was raised by Aninda Das,
which most of the programmers often overlook – not intentionally, but due to huge
work pressure, lesser time at hand and crisis of resource.
‚What is the importance of documentation in programming? I know many developers;
start-ups/SMEs skip this process. May be they do not have the bandwidth or the client
does not emphasize much on it. BUT the documentation is critical. Let us discuss the
relevance of documentation. After all ‚Ink is better than the best memory‛ – Chinese
proverb‛, is what Aninda posted to stimulate the IT professionals to share their views,
experience and knowledge.
Quoting from a blog that Bibhas follows he said, ‚No matter how wonderful your
library is and how intelligent its design, if you're the only one who understands it, it
doesn't do any good‛.
Ulhas sharing his thoughts said, ‚Documentation is required big time in programming
for the developers themselves as we go on coding and at times we are not able to
recognize what we coded if the code gets a bit older‛. He also added that he follows a
2. certain methodology of documentation, which he himself created. ‚I do try to make the
documentations as in comments in the scripts itself‛. The biggest problem faced by
most of the programmers is time crunch to meet the deadlines. Ulhas cited added a
practical scenario which can’t be looked down up on. ‚The clients comes to the context
they are hardly interested in the documentations for the programming instead they
want the documentation for "HOW TO USE THE FINAL PRODUCT?" as in training
themselves as well as their employees‛.
Prashant feels that every standard software development processes must follow
documentation. He also mentioned, ‚The output of many phases of software
development is often a document‛. A few examples of which can be Implementation
Plan, SRS/FRD, Design Document, Test Plan and Test Cases, and End User
Documentation. Sharing some further insights to program documentation he added,
‚Fellow coders who require to understand the code for maintenance/enhancement,
plug-in developers who require API documentation. Programmers themselves often
require design documents. There are automated tools like Doxygen which make
documentation easy and not too much of a strain on programmers. But a certain
discipline in the software development process is needed, otherwise programmers tend
to ignore this critical aspect‛.
Arjun not agreeing completely to this process feels, ‚there are different paradigm when
it's comes to developer/spec documentation which does not insist on traditional
documentation‛. Scrum/Agile/Lean can be some perfect examples of the same which
puts more emphasis ‚on the concept of "code-as-comment" and spec documentation via
RSpec/Cucumber StoryBoard scenarios which acts as user-acceptance documentation as
well as executable spec code!‛ documentation is different for developers, PM/Delivery
Managers, Testing Groups, Marketing/Clients, and users. ‚But all these are essential
types of documents which are to be created in different ways as target is different and
so is its use and requirement! This has to be clearly understood!‛ he concluded.
Better codes for Rishav is better documentation. ‚I reject commits from my developers if
the code is not self explanatory. Writing tests is an awesome way of having
documentation. We do the tests thing all the time. Simple example – there are better
ways of hard-coding regular expressions into your code. Regexes are self explanatory.
Use a method instead simple and easy to read. As far as other types of documentation
are concerned architecture diagrams, spec docs and bug trackers are necessary‛. The
programmers need to document every feature in as much detail as possible.
Anupam harped up on the importance of documentation. He stated, ‚Documentation is
where your works starts. After that comes the very important part - the data flow
diagram and the database structure!!! As we all know programming is all about the
3. flow of data! Then comes the UI wire frames. Finally what I think we should create
another final doc. with everything put into right place before getting into code!‛
The waterfall model of documentation, Arjun added, is slowly getting abandoned. ‚The
days of bulky SRS or class diagram or HLD or LLD are going away fast!‛ He further
suggested to gather knowledge on, ‚’Agile’ especially ‘Scrum methodology’, ‘Lean
methodology’ & ‘Kanban’.
According to Priyankar, ‚Coding without documentation is like getting married in the
temple without getting it registered‛.
Mukesh further shared his personal reasons for which he follows documentation. With
three very practical yet simple examples he explained this further: ‚1. Collaborative
development -- there is always a need for X to help Y debug his/her code.
2. Maintenance -- you have written the smartest of code and you are done with
development. You move to a new project, someone else wants to change a small piece
of code. If there is no documentation, a 5 min change could easily take 5 hours.
3. What if you get hit by a bus? You were in the middle of solving one of the most
complex problems, you went out to bring food, got hit by a bus. You had solved 80% of
the problem but now the new guy has to start afresh.‛
Debashis stated the obvious need for documentation. ‚Each time a particular section of
code is updated, documentation for the same is imperative. It helps in rollbacks if
necessary‛.
Documentation is important for others to understand your code. To make your code re-
usable you must document it thoroughly. ‚Gone are the days when one coded with the
intention to just make the product work, now if 40% effort goes to the actual coding
then the remaining must go on making it re-usable and well documented for future
use‛, said Rabimba.
Arun, who said is a ‚fan of quick references rather than elaborate notes‛ also added,
‚We need documentation on all the aspects of the software, pre-sales and post-sales‛.
To make a developer’s life easy Mukesh suggested, ‚Clean readable codes, good use of
variable names, and code refactoring‛.
The takeaways from the discussion are huge. Through the experience shared by several
industry experts gave us some key factors of ‚What is the importance of documentation
in programming‛:
4. 1. The phases of software development documentation are: Implementation Plan,
SRS/FRD, Design Document, Test Plan and Test Cases, and End User
Documentation
2. To recognize what we coded, if the code gets a bit older
3. Documentation is necessary for, Programmers themselves often require design
documents.
4. Automated tools like Doxygen make documentation easy
5. Scrum/Agile/Lean are different paradigm of developer/spec documentation
6. For user-acceptance documentation as well as executable spec code spec
documentation via RSpec/Cucumber StoryBoard scenarios can be followed
7. Documentation makes your code simple and easy to read
8. Learning ’Agile’ especially ‘Scrum methodology’, ‘Lean methodology’ &
‘Kanban’ are important for documentation these days
9. Documentation offers immense support for maintenance
10. Documentation is important for others to understand your code
Post Submitted by: Sumana Chakraborty, Creative Writer & Blogger
Connect with us: Facebook: http://www.facebook.com/ITniketan , Twitter: @ITNiketan