General JavaDoc questions here:
How do I know if they are working? I know the format and what they're supposed to be doing, but how do I know if they're doing their job? Should it print out after compiling and running?
Another question - how many JavaDoc comments do I need? My professor really wants us to examine our methods in these commentaries, and explain any variables. Does that mean put it inside the method? or before the method but inside the class? or before the class?
Thanks for any help!
I think you may be a tad bit confused as to what JavaDoc actually does.
JavaDoc does not directly impact your program in anyway. JavaDoc is a means of compiling information about your program. Say you get a program and want documentation of what it does in a nice handy format. Common compilers like eclipse have an option to compile an html file full of documentation, just like it shows on the Java API documentation. https://docs.oracle.com/javase/7/docs/api/
This is all JavaDoc for the most part, it is generated from comments.
My teachers always tell me in regards to comments, you are not commenting for someone who doesn't read code. You don't need comments like....
// Prints out hello world
System.out.println("hello world");
A programmer knows this functionality already. Programmers are more interested in parameter names and what functions actually do. Example
/**
* #param a Number we are dividing into
* #param b Number we are dividing by
* #return Our quotient
*/
public static float divide(int a, int b) {
return (a/b); }
Will generate a page like this
Emphasis on the /** at the top, two asterisks denote that below contains JavaDoc. Most IDE's like Eclipse will highlight JavaDoc.
As you can see the names of the parameters are just a and b, in certain cases it is difficult to label parameter names by what their function may be, so it can save time to use JavaDoc to give a description of them, instead of someone scrolling through your code trying to figure out what the hell they do. You are creating a guide for your program to modify and update it.
JavaDoc is literally a guide to how all your functions, classes, variables work in your program.
I'm creating some unit tests with Jasmine and the test runner I'm using is Karma.
I'm also checking the code coverage of these test specs with the karma-coverage plugin.
I was wondering if there's any way of excluding certain functions from the code coverage itself and also from the Karma report (Istanbul actually).
I'm thinking that if the first one is solved then so is the second.
Pretty sure there's no obvious way of doing this, as I've looked in Istanbul as well (karma-coverage uses it) but maybe some of you run into this before.
It appears that the guy behind Istanbul has added support for ignoring specific sections of code from coverage analysis. Really useful!
More here: https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md
Use below lines of code to ignore code for coverage.
/* istanbul ignore if */ ---skips the "if thing" in the source code
/* istanbul ignore else */ ---skips the "else thing" in the source code
/* istanbul ignore next */ ---skips the "next thing" in the source code
Sometimes you want to ignore testing of the framework itself that you are currently using. That is typically the main reason for my need of this kind of functionality.
Is that function actually being used? If not, you can comment it or remove it completely. But if there's a reason for this function, then let the code coverage results point you out that this function is not tested!
Otherwise, could you put this particular function in it's own file and exclude this file from istanbul?
Can anyone tell me the different ways of commenting and what is the difference between /* and // type of commenting? I have used both and i have found /* one more useful but i couldn't understand the real difference.
In many languages // is used for a single line comment and /* */ is a multi-line comment and in java /** */ is used by javadoc to create documentation from your code. Commenting is just user preference, unless you are using something like javadoc. If you are using a compiled language, it is stripped out before it compiles. You can check out all the various types of commenting in many programming languages here
/** is useful too because software like doxygene read it
to generate a documentation fort function's core
Is there any need for code with author's name added in every function or even the files?
Yes code will be in source control and many programmers involved
According to Code Complete, comments are used to illustrate the purpose of the code. Using it for other purposes may result in 'comment decay'.
That said, keeping track of code ownership, change-log and who last modify the file, IMHO, is the job of a source control repo like SVN and such, and should not be inside the comments. Unless it is a license of some sorts. Or use an IDE's bookmark system to keep track of who authored a function, and who is the person responsible for it.
All this are just my 2 cent worth, though.
If the code is under source control, no.
That kind of data should be stored in the source code repository.
If the code is meant to be widely distributed (in other environment without any kind of repository), then yes, that could be useful. (some java sources do include that kind of information, as well as the release number from which some evolution of the code are available)
Obviously that kind of information (for widely deployed code base) is at the file level only.
Consider for example the source code of java.lang.Boolean in Java:
/**
* [...]
* In addition, this class provides many methods for
* converting a {#code boolean} to a {#code String} and a
* {#code String} to a {#code boolean}, as well as other
* constants and methods useful when dealing with a
* {#code boolean}.
*
* #author Arthur van Hoff
* #version 1.60, 05/05/07
* #since JDK1.0
*/
public final class Boolean implements java.io.Serializable,
Comparable<Boolean> {
[...]
You do not have all the authors from the beginning of time, only the most recent one, with the associated last major version for the most recent modification, and the version for the original introduction of the class.
That can help for API tooling for example, when you want to maintain good APIs.
But informations about the author is still limited to the file, not the functions: he represents the coordinator or aggregation manager for all the functions present in the class, even though there may have been more than one contributor over time.
As such, this is a public information, worthy of being put explicitly in the file, as opposed to a private meta-data (who writes what), stored as all other meta-data (date, version, branch, merge information, ...) in a source code repository.
Yes code will be in source control
Then no. Source control takes care of tracking this (blame).
Especially for team OpenSource projects, it might be useful or necessary to indicate the author of a particular piece of code. But commenting on every single function seems really excessive, especially since most of a class will be written by the same author (n’est-ce pas?). I like the Java library convention of specifying the author(s) for each class. Somehow, this seems to be the right trade-off.
On the flipside, if you co-authored a class, you’re to blame if someone else writes bad code in it. I actually think that this is a good thing. A class (in OOP, at least) is one entity so the quality is determined by its overall quality. If one function is bad, so is the whole class.
In some projects, author names can be used to give due credit to someone who put more effort into development than expected of him. Such recognition can improve motivation.
No. You or the company you work for implicitly has copyright. But that being said for tracking purposes it can be useful to ask that person what this code did later.
yes it is needed. Also if possible give the date alongwith the name. It is used for the tracking purpose as well as gives priviledge to others to know the owner of that function.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
I'm wondering if people have a standard format for comments in their code. Not things like xml comments for a method or class but rather comments within a method.
See also:
Is there a standard (like phpdoc or python’s docstring) for commenting C# code?
You should really consider a couple things to make good comments beyond formatting.
Do not simply restate what the code is doing. For example,
// Start the services
StartServices();
is a frigging terrible comment!
Describe why. Why is the code doing what it's doing? What's the business assumption or algorithm step?
Format your comments for maximum readability. Tab them properly, leave spaces where necessary, etc.
If someone has already started commenting in a standard way, don't break that standard.
Check this article on MSDN about writing effective comments: http://msdn.microsoft.com/en-us/library/aa164797.aspx
// I usually write comments like this
Where I work it is required to use standard xml comment style for most of the declarations (classes, methods, some properties) (we use C#).
Sometimes you can see header/footer comments in use.
/****************************************************/
// Filename: Customer.cpp
// Created: John Doe
// Change history:
// 18.12.2008 / John Doe
// 14.01.2009 / Sara Smith
/****************************************************/
/* Here goes a lot of stuff */
/****************************************************/
// EOF: Customer.cpp
/****************************************************/
Something like this was used at one of my old places of work. In my opinion too much of unnecessary stuff. Change history is nicely seen these days through a version control system.
In many good software shops there are internal guidelines as to when and how to write comments. Documents are typically referred to as "Source code style policy" or something. It is very important to adhere to one common style in commenting the code.
Of course this commenting hype shouldn't go too far as to comment every little piece of code, especially the obvious ones.
/// <summary>
/// Handles the standard PageLoad event
/// </summary>
/// <param name="sender">
/// Event sender
/// </param>
/// <param name="e">
/// Event arguments
/// </param>
public void Page_Load (object sender, EventArgs e)
{
// Do something here
}
This one is a good example of over-obsession with commenting. Something like this adds exactly zero information but only adds noise to the source file. And we have to do it at work as required.
My personal opinion is add comments when you have something to say or explain, not just for the sake of commenting everything.
/**
* block comments to document a method for javadoc go like this
* #param
* #return
* #exception BTKException
* #see BTK
*/
Comment on the line above the code (block) that does what you're describing
// This is a comment.
Some code goes here
Avoid doing stuff like
// ----------------
// IMPORTANT COMMENT
// ----------------
And I avoid using the
/* comment */
And perhaps most importantly, clean up comments! A comment that describes non-existent functionality is worse than no comment at all.
//For one line, I write them like this
/*
For multiple lines of text
I write them like this
*/
/*
for(multiple lines of code){
I.WriteComents(With("//"));
Reason==If(I.Remove('The top begin-quote mark') then
I.Worry.Not('About removing the close-quote mark');
//*/
The problem with comments within a method (rather than in an interface), is that they are actually not meant to be seen by anyone except for people maintaining that method. Therefore, there is no real need for a standard for the comments. They don't get published anywhere, they're not publicly visible, callers will generally never see them.
In general, comments inside code should follow four rules:
They should not state the obvious
They should be consistent with what they describe
It should be clear what they describe (e.g., which line, block).
They should be readable by any future maintainer.
That being said, there is often a tendency to place information that is important to the callers as an internal comment. For example: "OOPS, This doesn't handle negative numbers". Whenever you see an internal comment, reconsider whether the header documentation should be updated, or use a tool that "pushes" the comments to the awareness of function callers (I have a tool like that for Java).
/* I will sometimes write
comments like this */
I can't believe we missed the REM keyword.
Though to be fair, it's for REMARK not COMMENT.
# ----------------------------------
# BIG IMPORTANT COMMENTS IN PERL/SH
# ----------------------------------
Comments standards are most useful when the comment will be parsed by an external tool (usualy, a document generator, like javadoc).
In this case, the external tool will state the standards.
For other cases, see How do you like your comments? (Best Practices)
//Cheap Debugger
//Response.Write(MySQLStringBecauseINeedToKnowWhatsBroken);
' I usually write comments like this
<!--How about comments like this!?-->
There are packages that will help write and format documentation. They require some specific changes so they can identify classes of comments.
such as doxygen:
http://www.doxygen.nl/manual/docblocks.html
/*! \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
(* Modula-2 comments go like this *)
If you are paranoid and don't use or trust source control, you might do this
// Initials-YYMMDD-fixNo-Start
dosomething();
// Initials-YYMMDD-fixNo-Finish
It makes a bloody big mess, but it gives you some way to rollback changes.
But I'd suggest using source control
There can be religious wars on this subject.
What I try to do, that doesn't cause too much warfare, is
// explain the purpose of the following statement in functional terms
... some statement ...
The idea is, if I run the code through a program that deletes everything except the comments, what is left is pretty good pseudocode.
Something that's useful as a way to comment out code that you think you might need again is:
/*
... some code ...
/**/
then modify the first line - either delete it, or change it to /**/
/**/
... some code ...
/**/
/*
* Brief summary of what's going on.
*/
int code_that_goes_on(int c)
{
/* and then if I have to remark on something inside... */
return 0;
}
99% of compilers will support // comments, which is awesome, but that 1% still exists, and it's not too difficult to make life livable for them.
EDIT: The Delphi comment is a bit obtuse, but does point out a real deficiency. I intend this to be a C-specific answer.
I don't think there is a standard for what you are asking. And I don't see how it would add any benefit from /// comments on the method itself.
For creating documentation from your C# classes take a look at Sandcastle.
In C/C++/C#/Java, when I have a comment explaining a block of code:
// comment
code;
more_code;
when a comment is explaining a single line:
code; // comment
I usually use // for single sentence comments and /* ... */ comments for multi-sentence comments.
One comment style in C++/Java etc is this:
// Use // for all normal comments...
// and use multiline comments to comment out blocks of code while debugging:
/*
for(int i = 0; i < n; ++i) {
// If we only use // style comments in here,
// no comment here will mess up the block comment.
}
*/
I think it is an interesting point, even if it's not that incredibly useful.
My code is self-documenting. I need no comments.
I'm surprised that not more people recommended doxygen. It is a good way of documenting code, with the side effect that it can automagically generate html + pdf API documentation at the end of the day.
I prefer commenting this way for function
/**
* Activates user if not already activated
* #param POST string verificationCode
* #param POST string key
* #return true on success, false on failure
* #author RN Kushwaha <rn.kuswaha#gmail.com>
* #since v1.0 <date: 10th June 2015>
*/
public function activateUserAccount() {
//some code here
}
I use single line comment for code descriptions like
//check if verificationCode exists in any row of user table
code here
You might want to at least consider using standard comment formats for the PHP Reflection Class: https://www.php.net/manual/en/reflectionclass.getdoccomment.php
My sites compress html so a comment like
// comment here
in JS will crash the java script.
The specs for using // in PHP is only supposed to be a "short comment" ie: one line. Personally I don't think they should be used for more than one line.
Using them also makes it impossible to compress - or a lot harder to compress than what it should be.
Lastly.
Human interpretation is NOT absolute - a computer code is :)
So if you have a code that needs to or should be read - (Go Nasty) and don't comment it. ie: Force the reader to read the code rather than you relying on their interpretation of your comment.