5

I'm wondering if there is a standard to write comments in APEX ?

In order to pass the Security Review, I review my code. And I think writing good comments in APEX classes can help the reviewers to understand the code.

For example, if we want to generate the Javadoc, we have to do something like this :

/**
 * Returns an ...
 * <p>
 * This method ... 
 *
 * @param  name  the name ...
 * @return      the string ...
 */
 public String myMethod(String name) {
        ...
 }

So does any comment standard like the code above exist ?

And does a tool to generate the documentation exist ?

8
  • See Documenting Salesforce.com Apex class files. Having clear names for classes, methods and arguments (including test cases) gets you a fair way to understandable code, and the documentation shouldn't just duplicate what is already clear from the code. (Remember that anyone looking at your code is seeing both the code and the comments unlike for Javadoc where often API documentation is looked at in isolation.) I would focus on the class-level comments more than the method-level comments. – Keith C Oct 7 '14 at 12:37
  • Ok, so you think I just have to write some comments on the source code and not include them in the documentation ? – SF_user Oct 7 '14 at 12:41
  • Its a while since I did a security review, but I didn't supply any separate Javadoc-style documentation. See what others think though. Helping the reviewer understand your code through overview documentation of some sort certainly makes sense. – Keith C Oct 7 '14 at 12:48
  • 1
    Are comments actually necessary for a security review? Aren't these done automatically through code parsers? Like checking if test class has assert statements or 'with sharing' in a class? – akash Oct 7 '14 at 14:08
  • I don't really know if comments are mandatory but I think it's better, not only for reviewers but also for our developers team, to have a well-commented code. – SF_user Oct 7 '14 at 14:11
3

Apex2Doc is similar to JavaDoc. Not necessary for security review, I don't think. But useful for the next person to edit your code.

3

There is no built in support for JavaDoc style comments in Apex, nor are they required for the security review.

ApexDoc is a popular solution for generating documentation from JavaDoc style comments, but the syntax is quite restrictive and it has not been updated in nearly 3 years.

SfApexDoc is an updated version with slightly less restrictive syntax and a number of other enhancements, its also being actively developed (albeit slowly).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.