-2

I have to call a function from main function like:

void main()
...
...
...
printf("Starting function- saveSubscriber");
  status = saveSubscriber(io_ctr,
                   i_pRec,
                   /*&ufpEsn,*/     **/* Change #6*/**
                   iov_pmktbuf,
                   &i_pCntRec,       **/* Change #23 */**
                   iv_pActvBuf->pr ); 

...
...
}

Is putting comments beside arguments (/* Change #6*/ and /* Change #23*/) okay? That is, will the code compile and will it function the same as when there are no comments.

Gary99
  • 1,750
  • 1
  • 19
  • 33
Mishti
  • 47
  • 6
  • 4
    Sure. But this is an opinion question and therefore OT – David Hoelzer Aug 17 '18 at 11:04
  • 4
    Yes it is perfectly fine and the normal way to comment on complex function calls. – Lundin Aug 17 '18 at 11:04
  • 2
    Yes, it is absolutely fine. Compiler skip these comments during Lexical Analysis phase. – Safwan Shaikh Aug 17 '18 at 11:08
  • The *contents* of the comments aren't great, though - that's the sort of information that's managed for you by your source-code repository tool. Good comments convey immediately-useful information to the reader. – Toby Speight Aug 17 '18 at 11:15
  • Thank you all. I don't remember but I read somewhere that putting comments like this during function call may create some issue, don't remember what and where I read this, so asked! – Mishti Aug 17 '18 at 11:22
  • To track changes, use a revision management/repository system like git or svn. Comments like this ill eventually adn very quickly result in chaos. – too honest for this site Aug 17 '18 at 12:28

2 Answers2

4

The comment syntax is fine.

For me commenting arguments is a sign, that the name of the argument is not chosen clearly.

Moreover, commenting out a complete agrument leaves me a bit puzzled. It seams like somebody changed the signature of the function and was too lazy to clean it up properly.

schorsch312
  • 5,553
  • 5
  • 28
  • 57
  • 1
    "commenting arguments is a sign, that the name of the argument is not chosen clearly" The comment may as well tell what that particular parameter of the function _does_, not so much to document what the particular argument _is_. – Lundin Aug 17 '18 at 11:16
  • Thank you all. I don't remember but I read somewhere that putting comments like this during function call may create some issue, don't remember what and where I read this, so asked! – Mishti Aug 17 '18 at 11:22
0

This is perfectly fine, as others have said.

However, you might be able to avoid this if you use meaningful variable names.

I also find myself declaring a lot of differently named enums, which are basically just Boolean.

Which is clearer?

1) 

processData(1);  // you might add acomemnt to explain what 1 means.
                 // Many won't bother (especially those @~£%$!! who write  
                 // code that I have to main years later !!)

2)

#define TRUE 1
#define FALSE 0
...

processData(TRUE);

3) 

typedef enum {deleteDuplicates, retainDuplicates} howTohandleDuplicates_t;

processData(deleteDuplicates);

Always try your best to write maintainable, easy to read, code. Comments are fine, but well chosen variable names can obviate the need for most of them

Mawg says reinstate Monica
  • 38,334
  • 103
  • 306
  • 551