Page Comparison

Making code readable and accessible helps your team communicate and reduces wasted time when making changes to scripts. The ideas outlined here are guidelines based on experience and will give your team the ability to understand how your system is set up and track changes to the system.

...

• A brief description of what the routine function does.

• A description of each parameter and a description of what each parameter represents.

/**
* Lists all the files in a given directory tree. 
* @param dirName - The path of directory to search
* @param excludes - A list of directories or files to exclude from results
* @return The list of files found in the directory
*/
function directoryFiles(string dirName, string[] excludes) {
  // rest of routinefunction here
}

Conclusion

For a complete explanation of commenting, see this Oracle page on commenting code.

...