Re: Encouraging good comments Which language ?

[Sean Conner <sean@...>]

It was thus said that the Great HyperHacker once stated:
> On Mon, Jan 30, 2012 at 00:40, Patrick Rapin <toupie300@gmail.com> wrote:
> >> What language is most likely to encourage good commenting ( What is being done and why ? )  and make the code easier to support by a future maintainer  ?
> >> Or is this just not something that is influenced by the language......
> >
> > Personally, I only write extensive comments in Assembly language, and
> > for complex Perl regular expressions...
> > Because otherwise, I cannot read back my own code.
> > IMHO, Lua does not encourage good commenting, because the language is
> > already quite clean.
> > It is easier to maintain uncommented Lua code than a well commented
> > one in assembly language !
> >
> 
> True, ideally your code would be so clear and readable that comments
> aren't even necessary, but I think that may never be a reality until
> computers can understand natural language...

  And even then ...

  In syslogintr [1], here's the main loop (some parts omitted for this
discussion):

	int main(int argc,char *argv[])
	{
		/* ... */
	  set_signal_handler(SIGINT,handle_sigal);
		/* ... */

	  while (!mf_sigint)
	  {
		/* ... */
	  }

		/* ... */

	  set_signal_handler(SIGINT,SIG_DFL);
	  kill(getpid(),SIGINT);
	
	  return EXIT_SUCEESS;
	}

  The program runs until it receives a SIGINT.  What happens afterwards it a
bit odd.  I mean, it's straightforward (and those *are* the last lines of
code in main()) but utterly mysterious as to *why*.  *THAT'S* when you add a
comment.  And that's what I have (direct dump from the source code):

  /*------------------------------------------------------------------------
  ; Per http://www.cons.org/cracauer/sigint.html, the only proper way to
  ; exit a program that has received a SIGINT (or SIGQUIT) is to actually
  ; use the default action of SIGINT (or SIGQUIT) so that the calling
  ; program can detect that the child process (in this case, us) actually
  ; received a signal.  So that's why we set the default handler for SIGINT
  ; and kill ourselves, since the only way we get here is via SIGINT (or
  ; possibly SIGQUIT if/when I add logic for that).
  ;------------------------------------------------------------------------*/

  set_signal_handler(SIGINT,SIG_DFL);
  kill(getpid(),SIGINT);

  return EXIT_SUCCESS;  /* keep this around to silence the compilers */
}   

  Also, the code to become a daemon is relatively straightforward:

	int daemin_init(void)
	{
	  pid_t child;
	  int   fh;
	
	  child = fork();
	  if (child == -1)
	    return -1;
	  else if (child != 0)
	    _exit(EXIT_SUCCESS);
	
	  setsid();
	  signal(SIGHUP,SIG_IGN);
	  
	  child = fork();
	  if (child == -1)
	    _exit(EXIT_FAILURE);
	  else if (child != 0)
	    _exit(EXIT_SUCCESS);
	
	  chdir("/");
	  umask(022);
	  
	  fh = open("/dev/null",O_RDWR);
	  if (fh == -1)
	    _exit(EXIT_FAILURE);
	
	  dup2(fh,STDIN_FILENO);
	  dup2(fh,STDOUT_FILENO);
	  dup2(fh,STDERR_FILENO);
	  close(fh);
	  return 0;
	}

  But this straightforward code doesn't begin to explain *why* we fork
twice, nor why we change to the root directory or ignore a particular
signal.  Now, I don't need comments because I know why this code works.  But
it does.  There are no bugs in this code (if there are, it's in the Unix
kernel, because all this does is call into the kernel) so there's no real
need to touch it (but the code I pulled this from lists the reason behind
*each line of code*---the comments are over twice the length of the code).

  -spc (who has done his fair share of "increment the counter" type
	comments)

[1]	A syslog daemon written in C/Lua, so it's at least on topic.
	http://www.conman.org/software/syslogintr/