Coding Policy of Hands-on
- Overview
- 1. Reviewable Code
- 2. Resolving IDE Warnings
- 3. Write Class Javadocs, Even If Only the Bare Minimum
- 4. Empty Line Management
- 5. Comments that Provide Context
- Special Thanks
Overview
I have compiled this recommended coding policy for DBFlute Hands-on and javatry.
Your actual development team may have a different coding policy. Still, the ability to adapt quickly to your workplace's policies and write code accordingly is also an important skill.
Instead of coding however you want, try and get used to writing code based on some sort of coding policy — even with the code you write for this training.
1. Reviewable Code
This is the general theme behind various coding policies.
- Who is the first to read code?
- Needless to say, it's the reviewer.
- If the code is reviewable,
- → the review will be faster and more thorough
- → it will be easier to find bugs
- → it will be easier to release the code, even those written by inexperienced programmers
- → it will be easier for an experienced programmer to write critical code
It is safer if bugs can be found and fixed before a piece of code is released. And though it is also important to strive to write code without any bugs in the first place, making it easy to identify areas that may produce bugs would help ensure that you release code of higher quality.
You can say that reviewable code is market-ready code. And it can also be of help to the programmer themself. But what exactly is reviewable code? Keep that question in mind when you develop software.
But there is more to it than that. Please read my blog for more info.
2. Resolving IDE Warnings
Be careful not to commit code when IDE like Eclipse or IntelliJ displays warnings. (It's a waste of time for humans to review things that can be checked automatically.)
It's alright to ignore suggestions and hints from the IDE, but make sure you don't leave too much of them that it clutters up your IDE. Adjust your IDE's settings if you are getting too much unnecessary warnings. (In particular, I have found that IntelliJ makes a lot of unnecessarily specific suggestions.)
Time can be spent reviewing more important aspects of the code if low-level mistakes are corrected beforehand.
3. Write Class Javadocs, Even If Only the Bare Minimum
Write a comment expressing the contents of the class, even if it's just one line.
Also, use the @author tag for class Javadocs. (type @au, and autocomplete with ctrl + space, if you're using Eclipse)
e.g. Minimal JavaDoc, one-line comment and author @Java
/**
* Action Class for the Product List Search Page
* @author jflute
*/
public class ProductListAction extends ... {
...
}
Add an @author tag if you modified a class written by somebody else (except for review comments).
e.g. when stojkovic modifies a class written by jflute @Java
/**
* * Action Class for the Product List Search Page
* @author jflute
* @author stojkovic
*/
public class ProductListAction extends ... {
...
}
You can also look at the commit history to find out who modified a file, but the point is to make it known as soon as you open the file.
You may have to take over developing from someone else, especially in incremental development environments. More often than not, multiple people will be involved in a piece of code. And there will be many situations where you have to read code in an emergency. So I think it's important to know "who to talk to" immediately.
When multiple people modify a piece of code, it becomes easier to be irresponsible and write code that only works for limited scenarios. Another purpose for this is to make you conscious that you are involved in the code by deliberately signing it.
4. Empty Line Management
Empty lines play the distinct role of demarcation.
Randomly inserting or deleting empty lines will make the structure of your code hard to understand. There are no absolute rules to be followed, but try to, first of all, be consistent, and bear in mind to make it easy to understand the intention of your code at a glance.
Most computer displays are wide but short, so delete unnecessary empty lines (ctrl + D on Eclipse). But of course, don't hesitate to use empty lines when there is reason for them.
Example of Bad Empty Line Management ×
Not to say the following is completely wrong, since consistency should also be considered, but the division between processes is unclear, especially in the index() method.
e.g. Code with poorly managed empty lines, using LastaFlute's example @Java
/**
* Action Class for the Product List Search Page
* @author jflute
*
*/
@AllowAnyoneAccess
public class ProductListAction extends HarborBaseAction {
@Resource
private ProductBhv productBhv;
@Resource
private PagingAssist pagingAssist;
@Execute
public HtmlResponse index(OptionalThing<Integer> pageNumber, ProductSearchForm form) {
validate(form, messages -> {}, () -> {
return asHtml(path_Product_ProductListHtml);
});
PagingResultBean<Product> page = selectProductPage(pageNumber.orElse(1), form);
List<ProductSearchRowBean> beans = page.stream().map(product -> {
return mappingToBean(product);
}).collect(Collectors.toList());
return asHtml(path_Product_ProductListHtml).renderWith(data -> {
data.register("beans", beans);
pagingAssist.registerPagingNavi(data, page, form);
});
}
}
Example of Good Empty line Management ○
In contrast, Empty lines match the division between processes in the following code.
Of course, everyone has their own opinion on what meaningful demarcation is, so this is only for reference. But I hope that you consciously manage Empty lines with some sort of consistency.
e.g. Demo code with well managed Empty lines, using LastaFlute's Example @Java
/**
* Action Class for the Product List Search Page
* @author jflute
*/
@AllowAnyoneAccess
public class ProductListAction extends HarborBaseAction {
@Resource
private ProductBhv productBhv;
@Resource
private PagingAssist pagingAssist;
@Execute
public HtmlResponse index(OptionalThing<Integer> pageNumber, ProductSearchForm form) {
validate(form, messages -> {}, () -> {
return asHtml(path_Product_ProductListHtml);
});
PagingResultBean<Product> page = selectProductPage(pageNumber.orElse(1), form);
List<ProductSearchRowBean> beans = page.stream().map(product -> {
return mappingToBean(product);
}).collect(Collectors.toList());
return asHtml(path_Product_ProductListHtml).renderWith(data -> {
data.register("beans", beans);
pagingAssist.registerPagingNavi(data, page, form);
});
}
}
Let me give an example using DBFlute's hands-on code.
e.g. Demo code with well managed Empty lines, using DBFlute's Example @Java
/**
* DBFlute Hands-on Section 2 test Class
* @author jflute
*/
public class HandsOn02test extends UnitContainertestCase {
@Resource
private MemberBhv memberBhv;
public void test_demo() throws Exception {
// ## Arrange ##
String prefix = "S";
// ## Act ##
List<Member> memberList = memberBhv.selectList(cb -> {
cb.setupSelect_MemberStatus();
cb.query().setMemberName_LikeSearch(prefix, op -> op.likePrefix());
cb.query().existsPurchase(purchaseCB -> {
purchaseCB.query().setPaymentCompleteFlg_Equal_True();
});
cb.query().addOrderBy_Birthdate_Desc();
});
// ## Assert ##
assertHasAnyElement(memberList);
memberList.forEach(member -> {
String memberName = member.getMemberName();
log(memberName);
assertTrue(memberName.startsWith(prefix));
});
}
}
5. Comments that Provide Context
First of all, write as much comments as you can. It is easy to forget to write comments when coding for a training course. But try to write code during your training as if you were actually coding for work, for the sake of the reviewer.
In particular, write comments that provide context. Reviewers want to know why the code was written the way it is. (Comments providing information that cannot readily be deduced from the code are most helpful to reviewers.)
Please do read the following blog for more information.
Database Comments are also Comments
Comments are not restricted to code. You can also write comments for a database table or column.
Function and Variable Names are also Comments
Comments are not restricted to code. Function and variable names are also important comments.
Special Thanks
Cruz, thank you for your translation.
