Including commented Class declaration in implementation file

Everyone knows the advantages of a more readable code. So in order to make my code more readable what i do normally is include the commented class declaration in the implementation file of that class.
This way i need not have to browse through various include directories to go to the definition.
So, Is this a good practice or just over-documentation?
If there is some standard technique, plz let me know.
EDIT:
Is there a way to migrate to class declaration from implementation in Vim ?
Except opening it in new buffer.

Thanks

--------------Solutions-------------

This is actually counter-productive, because now you have to change three locations instead of two when modifying class declaration, and one of these locations won't be checked by compiler to catch any mismatches.

Also, in large and quickly-evolving projects comments always get obsolete, so they cannot be trusted.

All modern IDEs can help to access class declaration from class implementation in a number of ways, all of which are more convenient than scrolling to the top of file and then back.

As an alternative, consider using an auto-documentation tool such as doxygen. Doxygen can be told to include entire class declarations in the documentation -- with syntax highlighting, line numbers and links to the source files. You can include a doxygen pass in your build process and always have an up-to-date code reference.

This breaks the DRY principle : you have to maintain the comments when you change the declaration.

And it will not help a lot read your code.

As they say (from memory) : "If the code and the comments tell different stories, they're certainly both wrong."

What will help is :

  • make sure your class declaration in the header is well documented and/or pretty clear about the class usage : that's where most of the users of the classes will look first because that's the "manual" of your class (be it comments or explicit functions);
  • write those comments in a way telling your intention, not what it will do exactly : the intention is what it should do, not what it does (if it's buggy) -- that way you give clues to other people (or yourself later) to fix bugs in your implementation because they can understand what you tried to do;
  • don't report your header comments in your definition file (cpp) because it will be redondant!
  • write comments in the definition code where you need to tell the intention and where what you do might not be obvious;
  • if possible, replace comments in implementation code by real code (function or class) : you can often encapsulate a code block in a function with an explicit name or the result of an operation in a variable with an explicit name -- programmers will more thrust executed code than unclear comments....

This does not help a lot, because when class definition is bigger than one screen, your colleagues will have to scroll up to get to the declaration. Modern IDEs are very good in locating the declaration so IMHO this is useless.

The only thing which really matters sometimes is that you put the access identifier in the comment when you define the function. This really saves time for someone trying to understand the code.

Something like this is enough:

//private
void Car::ReplaceDriver(const std::string & NewDriver)
{

}

I'd consider it over-documentation and have never seen it elsewhere. When modifying the class the comments will be out of sync quickly (or looking there you are never sure).

Not sure what environment you use, but when looking for a declaration, I normally use a function of the editor (on Mac Xcode and Windows VisualStudio you can right-click something and then jump to it's definition or declaration).

Category:c# Time:2009-11-17 Views:1

Related post

  • Objective C: ARC with IVars declared in implementation file 2011-12-17

    I found an interesting post describing how, in Objective-C 2.0, instance variables can be declared in the implementation file. Consider this example: @interface MyClass {} @end @implementation MyClass { NSObject *obj1; NSObject *obj2; } @end Notice t

  • Doxygen comments on declarations or on definitions? 2009-11-23

    Just started using Doxygen for documenting my code here and can't decide where to put them. At first look it seems better to put them in the declaration files as it is there where you actually declare what you receive, what you are going to return an

  • Should '#include' and 'using' statements be repeated in both header and implementation files (C++)? 2010-04-26

    I'm fairly new to C++, but my understanding is that a #include statement will essentially just dump the contents of the #included file into the location of that statement. This means that if I have a number of '#include' and 'using' statements in my

  • C++ header and implementation files: what to include? 2010-05-22

    There is a .h file and a .cpp file with the same name but different extension. If I want to use what's in the .cpp file, do I include the .h file or the .cpp file? --------------Solutions------------- The simple answer is that you almost always want

  • Objective-C: Is it ever Kosher to declare instance variables in the implementation file? 2010-11-10

    I've noticed that I'm able to declare instance variables in the implementation file of an Objective-C class. I understand there's a reason why I've been taught not to do this. Explained here. But it's so much nicer to not put them in the header, and

  • Helper classes - Private nested class vs. class declared & defined only in implementation file 2011-04-15

    I'm writing a basic SQLite wrapper. While doing this I noticed I'm frequently manually opening and closing SQLite databases, creating and destroying SQLite compiled statement structs using SQLite's API. Manually creating/destroying these resources. W

  • Instance variables declared in ObjC implementation file 2011-07-22

    I was watching the WWDC ARC introduction video and I saw something I've never seen in ObjC before when some Apple engineer talked about a Stack example. The following code was used for a stack example with ARC: @implementation Stack { // instance var

  • #import in header file or implementation file 2010-11-19

    Some have the habit of adding header file imports/includes to the header file. Some on the other hand, write a forward declaration in the header file and write the actual #include or #import lines in the implementation file. Is there a standard pract

  • C/C++ header and implementation files: How do they work? 2012-02-10

    This is probably a stupid question, but I've searched for quite a while now here and on the web and couldn't come up with a clear answer (did my due diligence googling). So I'm new to programming... My question is, how does the main function know abo

  • Confused about relation between header and implementation file 2012-04-18

    I'm working with Code::Blocks. When I create a header-file foo.h and put forward-declarations as well as implementation into it, compilation works fine. Creating a foo.cpp file and putting nothing into it still works. But when I include the header-fi

  • Variable declarations in header files - static or not? 2008-09-18

    When refactoring away some #defines I came across declarations similar to the following in a C++ header file: static const unsigned int VAL = 42; const unsigned int ANOTHER_VAL = 37; The question is, what difference, if any, will the static make? Not

  • Should I comment the declaration or the definition in C++? 2009-03-28

    Which is more practical to comment, the declaration (in the header file) or the definition (in the source file)? Maybe I should comment both, or comment neither and put it all in a separate file... --------------Solutions------------- You should comp

  • C : differences between prototype declaration in header and function declaration for implementation? 2009-04-05

    I was wondering about little differences between declaration of function prototypes in headers and in .c files. I have a header with some prototype functions and a some .c files with real implementation of these functions. I made some changes in the

  • XML Documentation Comments with Interfaces and implementing class(es) 2009-04-15

    I am documenting an assembly using XML Documentation Comments, from which a chm file will be created using Sandcastle. My assembly contains various interfaces, each of which is implemented by one class (in my scenario these are WCF services). I have

  • How to make XMLDOMDocument include the XML Declaration? 2009-07-17

    When an XMLDOMDocument saves itself, how can i get it to include the XML Declaration, e.g.: <?xml version="1.0" encoding="UTF-8" ?> <?xml version="1.0" encoding="UTF-16" ?> <?xml version="1.0" encoding="UCS-2" ?> <?xml version="1

  • Confusion with header and Implementation files in Objective-C 2009-09-19

    First off, please forgive the stupidness of this question but Im not from a C/C++ background. I'm a little unclear about what the difference in roles between the .h and .m files when it comes to properties. I understand the concept of interfaces, and

  • Why include header in the method definition file? 2009-12-10

    say you have a source file named sum.c that looks like this: #include "sum.h" int sum(int x, int y) { return x+y; } What's the point of including method's header in it's own definition file? Aren't you supposed to include it only in source files that

  • error on importing a .m implementation file 2010-11-23

    I was trying to import a .m file to use a static variable declared there in to another class. #import "Faculty.m" I got the error "No such file or directory". Now this might be a bad programming practice to declare variables in .m implementation file

  • Should you include source code in a header file? 2011-01-03

    I am working on porting some source code to a linux system, and as expected, some stuff is broken. One thing that is throwing an error for me right now, is that someone has a .h and a .cpp file that both use fclose() The compiler is complaining about

Copyright (C) pcaskme.com, All Rights Reserved.

processed in 1.713 (s). 13 q(s)