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 ?

Improve this question
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
    Commented Oct 7, 2014 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
    Commented Oct 7, 2014 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
    Commented Oct 7, 2014 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
    Commented Oct 7, 2014 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
    Commented Oct 7, 2014 at 14:11

2 Answers 2

Reset to default
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.

Improve this answer
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).

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .