Tuesday, July 26, 2011

How to write, good, RESUABLE comments without repeating yourself (DRY)

How to write good, reusable comments (DRY) ?
(Clean Code Quality Seal : Red)
Table of contents
How can i write good, reusable comments without repeating myself (DRY)?
How can i write reusable comments ?
Why do i think that annotations should be used as „post it“ and not as integral code elements?
Ok, but how can i make annotations powerfull and comments reusable?
How could it look like?
How does it look like in a real example?
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 good, reusable comments without repeating myself (DRY)?

Hi there! In this blog i wanna show you, how you can speed up your development process by taking profit of  the power of annotaations. Doing this way, you'll be developing cleaner, faster and applying the DRY (Don't Repeat Yourseft) principle automatically. Share this blog with your developers doing Know-How-Exchange. Make your code readable and comments reusable right now... In the next section i'll show you, how you can create reusable, uniform comments by writing less comments, saving a lot of valuable development time

How can i write reusable comments ?

Annotations are very powerfull additions in Java. But on my point of view, they should be used, as the name implies. To annotate and not to check and not to write code over that.

Why do i think that annotations should be used as „post it“ and not as integral code elements?

Well annotations are „static“ and hard coded. Once you annotate a type with the intention of write code based on this annotation, (what you can do and in some cases it really make sense) your code will be fixed on this annotation and changes on it are hard to be done without rebuilding the system, because it is in your code. The more annotations you have, the more static you’ll be making your code. I think we could check pre-conditions in a more elegant and flexible way, if you are using annotations just to check some conditions.

Ok, but how can i make annotations powerfull and comments reusable?

Well using annotations to mark your types bring a lot of synergie. Fact is : we would like a programm that does not need to be commented. Fact is : We would like a comment that is there, but does not appears in my source code, making my class huge and confusing me more then helping me. Fact is : Why do i have to write comments over and over again, if i could mark it? (annotate it) In fact we can do that. With a smart annotation you’ll get all reusable comments, you’ll gain overview in your classes, you’ll share your expirience motivating junior developers to use annotation and standard things can be annotated in the same, correctly and most important UNIFORM way, making corporate identity.

How could it look like?

Well i appreciate to use annotations to mark all the things it can be REUSED. Creating an annotation catalog all programmers will be using the same vocabulary and improving synergie and development speed with each iteration. In the annotation you can put(if nescessary) a good, explanatory comment with examples how to use the type and so on. I always write why and how i’m doing something or using something, NEVER what i'm doing. (this sentence is very important – note why and how, never what) Annotations make your source code readable and document it at the same time with concise keywords. Let’s see some examples :
The classic > database annotations: @Entity, @Bean, @Model and so on...
My favourits – Pattern annotations : @ObserverPattern, @StrategyPattern,@StatePattern 

How does it look like in a real example?

@Debug
public interface Debuggable {

   @ReferenceablePattern
   Debuggable DO = new Debugger();
   @Debug   void debug(final Class<?> clazz, final String method);
   @ReferenceablePattern   class Debugger implements Debuggable {

   @ReferenceablePattern
   private Debugger() {
     super();
   }

   @Override
   public void debug(Class<?> clazz, String method) {
   final String message = "class/method path: " + clazz.getName() + "/" + method;
   final Component noParent = null;
   JOptionPane.showMessageDialog(noParent, message);
   }

  }

}
As you can see, writing good, reusable comments makes your class thin, readable and the more annotations you have, the less you'll be writing comments again. i recommend you to catalogaze your annotations to make it easy to refind and reuse 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 πŸ˜±πŸ‘†

Monday, July 25, 2011

How can i indicate the quality of my clean code to other developers?

How can i indicate the quality of my clean code to other developers ?
(Clean Code Quality Seal : Red)
Table of contents
How can i indicate the quality of my clean code to other developers ?
How can i indicate the grade of cleanness in my code?
How do i establish the quality seals ?
When do i know if i should clean the code ?
When do i not have to seal the class?
How can i make the seals reusable to the whole company?
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 indicate the quality of my clean code to other developers ?

Hi there! !n this blog i wanna give you some ideas, how we can exploit the synergy in the company to our favor. (clean code developers) If you are familiar with Clean Code Development (CCD) and with the degrees it exits (black, red, orange, yellow, green, blue, white) you probably know how hard it is, to measure or indicate the grade of cleanness in the code. Here are some ideas that leave you and your code significantly stand out from the crowd.
If you are not familiar with the clean code development's degree system take a look at this first: Link

How can i indicate the grade of cleanness in my code?

Well the main problem is how to indicate the grade of cleanness of a class or peace of code, so that anyone knows, how clean or how "dirty" is a class or peace of code. For this purpose i've established quality seals. Usually you'll have a lot of developers in different stages of the clean code degree's system doing their work in the company. (because of the rotation principle of the clean code system)  It is also usual that developers review their code or the code from others to ensure quality and uniformity of checkstyle, etc. Which automatically means that developers with different skills and clean code stages will pass thru the code doing inspections, corrections and so on.

How do i establish the quality seals ?

Well, now instead of put an eclipse auto-generated copyright comment on the top of each class, that no one reads anyway (for this type of copyright comments you have other channels today) you could place a clean code quality seal. Here are the seal's pattern a make to copy / paste in your code. you post a seal from your actual degree and only if you realy did follow the principles and practises from your degree's color.
/**
*<pre>
*  +---------------------------------------------------+
*  + CLEAN CODE SEAL: RED - 25.07.2011 - R. Ferrira    +
*  +---------------------------------------------------+ 
*</pre>
*/ 
/** 
*<pre>
*  +----------------------------------------------------+
*  + CLEAN CODE SEAL: ORANGE - 25.07.2011 - R. Ferreira +
*  +----------------------------------------------------+ 
*</pre>
*/ 
/** 
*<pre>
*  +----------------------------------------------------+
*  + CLEAN CODE SEAL: YELLOW - 25.07.2011 - R. Ferreira +
*  +----------------------------------------------------+ 
*</pre>
*/ 
/** 
*<pre>
*  +----------------------------------------------------+
*  + CLEAN CODE SEAL: GREEN - 25.07.2011 - R. Ferreira  +
*  +----------------------------------------------------+ 
*</pre>
*/  
/** 
*<pre>
*  +----------------------------------------------------+
*  + CLEAN CODE SEAL: BLUE - 25.07.2011 - R. Ferreira   +
*  +----------------------------------------------------+ 
*</pre>
*/

When do i know if i should clean the code ?

Well that's very simple. If you pass thru the code (review, testing or refactoring) and you are corrently in a other stage as the current posted quality seal, you shall apply the principles and rules of your current degree and seal if after that. A second seal would look like this:
/**
*<pre>
*  +----------------------------------------------------+
*  + CLEAN CODE SEAL: RED - 25.07.2011 - R. Ferreira    + 
*  +----------------------------------------------------+
*  + CLEAN CODE SEAL: GREEN - 25.07.2011 - H. MΓΌller    +
*  +----------------------------------------------------+ 
*</pre>
*/

When do i not have to seal the class?

If you are currently in a degree that was already posted or if the class has all five seals already posted in it. With this simple "game" you'll learn a lot, become a very good professional and your company's code will be improved a lot. New developers (juniors) will be motivated and feel confortable in your company learning from the best developers.

How can i make the seals reusable to the whole company?

Well, that’s very simple. Just write annotations for it like this :
@CleanCodeSealRed
@CleanCodeSealOrange
@CleanCodeSealYellow
@CleanCodeSealGreen
@CleanCodeSealBlue

πŸ˜±πŸ‘‡ 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 πŸ˜±πŸ‘†