Monday, August 29, 2011

Why do you need a valuable system documentation?

Why do you need a valuable system documentation ?
Table of contents

How to write valuable system documentation with agile principles ?
How can i figure out if my documentation is valuable ?
How does the structure of a good documentation looks like?
Why do you need the system-documentation in this sequence?
How can i optimize my system documentation?
Don’t i need process documentation?
How can i avoid redundant documentation?
How could we improve the quality of this article ?
Source code convention tools
Literature, good books and references
How can i subscribe/feed this blog ?
Want to stay up to date ?
How can i rate this blog ?
Where do i find more clean code knowledge and gadgets?

How to write valuable system documentation with agile principles ?

Hi there! In this blog i wanna show you, why agile concepts need a valueable documentation and why to many developers missunderstand the agile manifest. You’ll see and understand how to structure the documentation, to figure out a good, valuable documentation saving a lot of time. This blog will give you some tequiniques and methods and best practices making your company more profittable as you always has dreamed of it. Share this expirience with other developers.

How can i figure out if my documentation is valuable ?

Well, to understand that, we must find out what is essencial needed and why! To do so before writting any documentation ask yourself those valuable questions:



Document purpose : Why do i really need this documentation ?

Documentation sort : How does the minimally systematic looks like ?



If you can’t aswer those questions, do not spend a lot of time writing something that nobody will read. We only write documentation if it brings an additional benefit.



Important: If it is possible to solve or clear something over conversation, favor this way over writing documentation.

How does the structure of a good documentation looks like?

Well first of all we must know, what kind of documentation a software really needs and how to differentiate between system-documentation and stakeholder-documentation.



A system-documentation looks normally like this acc. to the best practises :



·         Architecture overview (maintenance, build deployement, development)

·         Interface handbook (for external partners)

·         Operating handbook (for operation, installation etc.)

·         Admin handbook (for context administration)

·         Support handbook (after delivery and only if needed)



This was a template. To be sure you have covered the needs of your stakeholders show it to them and ask for feedbaks. It is always better to make pro-active a proposal because otherwise the stakeholders could say: i need it all or everything is nescessary.

Why do you need the system-documentation in this sequence?

Well thats a good and very important question, because here you get the reasons why it tis essencial to have it.


We can expect that the maintenance and support/service phase is avarage 3 times bigger than the construction phase. In agile contexts even much bigger because of the short delivery cycles. The system-documentation you need exactly for this phase. (For the life cycle after delivery). For this reason the system-documentation must document mainly all information you need to maintain and support the system without asking developers or getting know-how from experts, that may no longer work in the company.


Construction vs Maintenance (3-5 times bigger)

|__________|__________|__________|__________|__________|__________|

How can i optimize my system documentation?

Well the principle here is not what ist possible, but what is really nescessary. Project-documentation is not a system-documentation. Favor the direct conversation with the stakeholders and ask them what they really need and why. The system-documentation contains in most of the cases all information needed.


The only reasons to write project documentation are :


·         Big projects : If the direct project communication is not possible.

·         High risk : to control risks. Usually medical projects and projects for the state.

·         Law requirements : the law requires it.

Don’t i need process documentation?

Good question. Sure! Process documentation is an internal and structural documentation. The most companies has it already, since they are ISO-Certified. This kind of documentation defines rules, process, concepts, models, project plan, meetings etc. If your company does not have an established process documentation you should do ti now ! Don’t think you can live without it. This is only true if your company has 3-5 employees.

How can i avoid redundant documentation?

Example : You do not have to write additional documentation if the information is normally only available for developers. Cookbooks, Source code, JavaDoc etc. describe and help developers enough. Do not spend time, documenting those things. Developers will do it automatically, if they need. Instead you should insist on a cookbook by developers. (developers should do that at a minimum to ensure know-how-transfer)

😱👇 PROMOTIONAL DISCOUNT: BOOKS AND IPODS PRO ðŸ˜±ðŸ‘‡

Be sure to read, it will change your life!
Show your work by Austin Kleonhttps://amzn.to/34NVmwx

This book is a must read - it will put you in another level! (Expert)
Agile Software Development, Principles, Patterns, and Practiceshttps://amzn.to/30WQSm2

Write cleaner code and stand out!
Clean Code - A Handbook of Agile Software Craftsmanship: https://amzn.to/33RvaSv

This book is very practical, straightforward and to the point! Worth every penny!
Kotlin for Android App Development (Developer's Library): https://amzn.to/33VZ6gp

Needless to say, these are top right?
Apple AirPods Pro: https://amzn.to/2GOICxy

😱👆 PROMOTIONAL DISCOUNT: BOOKS AND IPODS PRO ðŸ˜±ðŸ‘†

Monday, August 1, 2011

How to avoid the violation of the DRY-Principle

Don’t Repeat Yourself (DRY-Principle) ?

Table of contents
Why do you need source code conventions in your company?
An other common violation of the DRY principle is this one here :
Do you want to stay up to date?
Source code convention tools
Literature, good books and references
How can i subscribe/feed this blog ?
How can i rate this blog ?
Where do i find more clean code knowledge and gadgets?

How to avoid the violation of the DRY-principle?

In this blog i'm gonna show you how to avoid violation of the DRY principle. The most important thing: i will tell you WHY you should not. I'm gonna give you some arguments, so that you are able to explain and motivate anybody at anytime.

What i hate, is the violation of the DRY principle by copy-pate or auto-comments. It seams to be a world wide "disease", because we all know it, but still continually violate this principle almost all the time. Let's figure out what i mean by doing a very trivial example:

Bad example 1 - DRY violation by repeating comments / making javaDoc obsolete:
/**
* The id
* @return id
*/ 
public long getId(){
    return this.id;
This example is so trivial, the most of the programmers would say one of those sentences: 
  • it's ok, any programmer with a little experience is able to understand that.
  • if a programmer does not understand that, then he is probabily on the false job
  • it would be better without comments.
  • it was auto-generated from eclipse. 
  • My checkstyle tool would fail if a did not comment it.
it sounds legtmin right? Well, if i was forced to do that, i would probabily say to my boss:
hey boss, i know you need me to do the work XYZ, but i have to rewrite (even better repeat)  some pieces of my code to accomplish the rules we have in your company
What do you think, he would say? OK, i think you got it...let's jump this part and see how it should be and why!
Good example 1: 
/**
* With this id you are able to retrieve the object from the 
* database by calling {@link DAO#get(id)} 
* @return id from the object to be retrieved
*/ 
public long getId(){
    return this.id;
1 rule: we comment not what, but why we do something.
2. rule: we write an example how to use it, because in a year nobody knows that anymore
3. rule: writing a good comment, motivates and encourages junior programmers to do it correctly also.
4. rule: the javaDoc does not become obsolete this way and really helps
5. rule: a good comment can reduce maintenance efforts, when a bug is issued
6. rule: agility has nothing to do with zero documents! thats not the meaning. agility, means sustainability means, re-usability, understandable clean code and so on....

Do you want to improve your development skills? Follow: @algoritmo4j

An other common violation of the DRY principle is this one here :


Bad example 2 - DRY violation unconsciously:

/**comment ommited */ 
public void doThis(Object o){
    if(o !=null){
         // do something here... 
        }
/**comment ommited */ 
public void doThat(Object o){
    if(o !=null){
         // do something here... 
        }
this is an also very trivial example, but a really good one. such constructs are very often. instead of doing this way, do better this way here:

Good example 2: 
/**comment ommited */ 
public void doThis(Object o){
    doNotAllowNull ( o ) ;    
     // do something here... 
/**comment ommited */ 
public void doThat(Object o){
    doNotAllowNull ( o ) ;    
     // do something here...
/**comment ommited */ 
private <T>  void  doNotAllowNull(T anyObjectOfYourChoice){
    final String msg = "YourExceptionHelpMessage"; 
    if( anyObjectOfYourChoice  == null){
          throw new NullPointerException(msg);
        }
Or this way here:
/**comment ommited */ 
private <T>  boolean  isNotNull(T anyObjectOfYourChoice){
    return ( anyObjectOfYourChoice != null ) ?  true  :  false
Even better: 
Even better it would be to define an interface and a class that does that for you so that you don't have to write or implement it always from the scratch. you just have to delegate it to this class.

Do you want to stay up to date?

bookmark www.treslines.com or follow: @algoritmo4j

Please rat it by clicking the google+1 or leaving some constructive comments or some bad examples from your companies and how you solve them. i also wanna learn from you. The next lesson will be: The KISS Principle. Stay connected and follow me. Do not miss it.

😱👇 PROMOTIONAL DISCOUNT: BOOKS AND IPODS PRO ðŸ˜±ðŸ‘‡

Be sure to read, it will change your life!
Show your work by Austin Kleonhttps://amzn.to/34NVmwx

This book is a must read - it will put you in another level! (Expert)
Agile Software Development, Principles, Patterns, and Practiceshttps://amzn.to/30WQSm2

Write cleaner code and stand out!
Clean Code - A Handbook of Agile Software Craftsmanship: https://amzn.to/33RvaSv

This book is very practical, straightforward and to the point! Worth every penny!
Kotlin for Android App Development (Developer's Library): https://amzn.to/33VZ6gp

Needless to say, these are top right?
Apple AirPods Pro: https://amzn.to/2GOICxy

😱👆 PROMOTIONAL DISCOUNT: BOOKS AND IPODS PRO ðŸ˜±ðŸ‘†

How to write less comments without looging context in your app?

How to write less comments (DRY-Principle) ?
(Clean Code Quality Seal : Red)
Table of contents
How can i write less comments witout loosing context in my app?
Do you want to see some examples?
Source code convention tools
Literature, good books and references
How can i subscribe/feed this blog ?
How can i rate this blog ?
Where do i find more clean code knowledge and gadgets?

How can i write less comments without loosing context in my app?

Hi There! In this blog i wanna show you that agility has nothing to do with "no comments". The most developers i know missunderstand the meaning of agile concepts, Xtrem-Programming and other agile concepts associating it automatically with no comments. Applications totally without comments works exactly as long as the code owner works in your company. In fact we can associate agility with LESS, reusable, concise comments. Here some ideas how to write agile comments making your code readable, understandable and reusable. Share this blog with your collegues doing know-how exchange.

How can i write readable, understandable comments?well to do that, we must understand how to comment in the different situations we have in our code. For this reason i have established some comment rules for myself:
  • private variables should comment itself (here you don't need more comments then that)
  • private methods should comment itself (here you don't need more comments then that)
  • public static variables should be commented inline over annotations (if possible and reusable)
  • static methods should be commented inline over annotations (if possible and reusable)
  • public methods should be commented over interfaces
  • private classes should comment itself (here you don't need more comments then that)
  • public static classes should be commented inline over annotations (if possible and reusable)
  • public classes should be commented inline over annotations (if possible and reusable)
  • Interfaces should be commented normaly
  • private constructors should be commented over annotations (@singletonPattern...)
  • public constructors should be commented over annotations (if possible and reusable)

Do you want to see some examples?

See "how to write good, reusable comments" - Link

😱👇 PROMOTIONAL DISCOUNT: BOOKS AND IPODS PRO ðŸ˜±ðŸ‘‡

Be sure to read, it will change your life!
Show your work by Austin Kleonhttps://amzn.to/34NVmwx

This book is a must read - it will put you in another level! (Expert)
Agile Software Development, Principles, Patterns, and Practiceshttps://amzn.to/30WQSm2

Write cleaner code and stand out!
Clean Code - A Handbook of Agile Software Craftsmanship: https://amzn.to/33RvaSv

This book is very practical, straightforward and to the point! Worth every penny!
Kotlin for Android App Development (Developer's Library): https://amzn.to/33VZ6gp

Needless to say, these are top right?
Apple AirPods Pro: https://amzn.to/2GOICxy

😱👆 PROMOTIONAL DISCOUNT: BOOKS AND IPODS PRO ðŸ˜±ðŸ‘†