Best Practices for Comments Above Methods in Grails Applications

commentsgrailsgroovy

I'm writing a grails application and am not sure what the best practice is with regard to comments outside of method blocks. I've done a bit of research and there seems to be conflicting views on how and when these sort of comments should be used.

In lots of source code I have seen there seems to be comments above every method detailing what that method does. I'm not sure if grails should be differnet?

My question is should I have a comment above each method in my controllers, services and domain objects?

i.e

/*
* This method displays the index page
*/
def index(){
render view : "index"
}

Best Answer

I dont think grails has implemeted different view for comments.

As comments are benefitial for codes as Comments ease comprehension by collecting information into one place.

It makes code understandable for developers who will need to work on the same code. As excess comments can be load use less and precise comments.

Use comments for

  • When you can't use a function name to explain something
  • Your intent behind a decision
  • Clarification of code you can't alter, like library call results
  • Warning of consequences
  • TODOs (to a reasonable degree)
  • Amplify the importance of something seemingly inconsequential
  • Javadocs in public APIs
Related Topic