Coding guidelines: Comments usage
Created by: smarek
Let us demonstrate the problem on current (or proposed update) of AIMSICDDbAdapter
class
Current: https://github.com/SecUpwN/Android-IMSI-Catcher-Detector/blob/25616a0fc0d185aa9e07c92ee5abddb0094ff4fd/app/src/main/java/com/SecUpwN/AIMSICD/adapters/AIMSICDDbAdapter.java Proposed: https://github.com/smarek/Android-IMSI-Catcher-Detector/blob/class-cleanup-3/app/src/main/java/com/SecUpwN/AIMSICD/adapters/AIMSICDDbAdapter.java
What are the questions:
- Can we simply remove comments which are just discussions ? (ie.
banjaxbanjo: What do you mean?
,EVA do I need to update an already known cell?
) - Can we slim down the comments (class, function, field) to effective javadocs for developing, with additional explanation on how the function works (using javadoc
@see
to refer to other methods, classes, ...) ? - Should we keep TODOs in comments to classes?
This class is not a rarity, all the classes have the problems, apart from deviating from coding standards, however the comments make the refactoring implementation much more painful, because it's hard to make changes, when there is not centralised issue management (issues / ideas / ...) are duplicated between source and issue tracker here on github, and from comments it seems like that there is currently somebody else working on the same particular part of code.
Can you provide your opinions please @E3V3A @SecUpwN @He3556 ?