Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
The structure of a FiM++ program requires that it end with the closing of a letter and the code author's name in a specific manner.
Dear Princess Celestia and Stack Exchange and String: A Sample:
...
Your faithful student, Southpaw Hare!
According to the language specification, the keyword "Your faithful student," (including the comma but not the following space) is used as an end tag for class definitions, and the following name is a comment with no syntactical effect.
The fact that the author is automatically included (if not strictly required) in every file makes me wonder if it can be used as a form of interpretable documentation akin to Java Docs. In other words, that other programs or editors would be able to parse out this name and use it in some manner.
What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?
Is the keyword sufficient to fit with the theme? It occurs to me that the lack of ability to use "Your faithful students," for a plural form (or possibly "Yours faithful," or "Yours truly," for an ambiguous version) would make listing multiple authors look awkward and unnatural (and looking like a natural human-written letter is one of the core design paradigms).
If creating a Java Docs methodology was considered, then what other features should be included? For one, a date seems common. Including some form of date comment at the top of the letter would probably look natural and not defy the design paradigm.
Since the language is new, unfamiliar to most, and honestly quite silly, here are a few resources to consider:
Original Release Announcement
October Followup
Sorry no one's given this any concern before me!
I'm heading development of the language, so I think I have a good grasp on the answer, here.
What is the requirement of such internal comment-based
documentation? Is there anything in this particular type
of syntax that would cause problems?
I've never considered an auto documentation technique like Javadoc, so there is no formal syntax for that. The compiler I'm working on completely discards comments, so it won't support it, but I'm sure it wouldn't be terribly hard.
Is the keyword sufficient to fit with the theme? It occurs to me
that the lack of ability to use "Your faithful students," for a
plural form (or possibly "Yours faithful," or "Yours truly," for an
ambiguous version) would make listing multiple authors look awkward
and unnatural (and looking like a natural pony-written letter is one
of the core design paradigms).
The idea of the author name on the last line was intended for the foremost author of the report, so multiple authors was never suggested before now. However, Your faithful students, would work nicely!
If creating a Java Docs methodology was considered, then what other
features should be included? For one, a date seems common. Including
some form of date comment at the top of the letter would probably
look natural and not defy the design paradigm.
Indeed! Perhaps something at the bottom of the report, like
(Written 2013-04-11)
Hope this help you. You have some great ideas, here, too! You should join the team!
For a programming project,
let's say the programmer has named similar style functions differently in many places, for example...
int ask_bro_4_data();
and another as
int ask_mom_for_data();
What antipattern does this represent? Essentially, it's the lack of standardization right? As in, one function uses for, the other uses 4.
Similarily the programmer could be naming variables in some fashion that relates to their use but fails to do so in every case, or does so in a non standardized way. This makes searching for these variables in a large code base harder because they may not be following the naming condition that you assume they would be.
Any ideas? Sorry for the ambiguous name, but I was not sure what to label this question as.
This would be considered more a syntax convention than a pattern.
The English language would lead us to prescribe using words in preference to numerals in order to improve maintainability. However, conventions can vary significantly depending on your peer group.
A design pattern would be considered a solution intended to address common problems introduced by a specific context.
For example; I want to ensure my application can only ever access the same instance of a given class. A basic pattern to address this problem would be the Singleton.
If the solution then introduces more problems than it solves; then it becomes an anti-pattern.
In this example; Singletons are hard to unit test; so this is one reason why many consider it an anti-pattern.
Anti-Pattern: Rename later
When the programmer realize that he/she or her collegues are inconsistent in naming and decide to do something about it later, or that is not important to do something about at all.
This can be coped with by:
clear guidelines from the team about what to strive for in respecting naming conventions,
recognizing that refactoring is an ongoing process, parallel to the coding.
simple IDE commands that afford the user after thinking oh we used "4" here and "for" here, that's disturbing *Ctrl+R Ctrl+R* ah that's better *continues coding.*
What is the frst step in OOD?
There are no steps, it's not a process.
The answer is..
(source: headfirstlabs.com)
http://headfirstlabs.com/books/hfooad/
http://www.amazon.com/dp/0596008678/?tag=forelangstud-20
Practice, read broadly and more practice.
Especially with others to review and comment on approaches.
Reading should cover not just OOD, but also patterns to see how others have approached common problems.
It's a lot of practice. The first thing is to get your mind around the way objects work--especially if you are a procedural programmer.
Practice making many small objects--I've literally never seen a system with too many objects; it's possible but I've never seen it. It should be really obvious when you need to put many objects into one, but it's not as obvious when an object should be broken up.
Ask an object to do something, don't ask for it's data. Try to avoid getters and setters and concentrate on methods where you ask it to do something with it's data. If you EVER see code like o.a=o.b+o.c or o.setA(o.getB()+o.getC() you are doing it wrong.
Constantly try to refactor out duplication. Rewrite your code repeatedly until there is none (or as little as possible). This will probably do more for your OO design skills than any other practice. As you get more knowledgeable, try refactoring things you didn't think you could refactor before. Anything that even looks like a pattern can probably be refactored. For instance here's a very basic example--if you had lines of code that looked like this:
a = b + c * d;
g = h + i * d;
Chances are there are HUGE refactorings missing in your code even though it doesn't look like it off the bat. You probably are missing an object that would hold a,b,c and a second instance would hold g,h,i, after creating these objects a bunch of stuff would factor into your new object. Learning to recognize new opportunities like this is critical.
I've been programming for over 20 years now, over half of it has been OO at this point and it seems like every few years I think I know it all--a year later I look back and realize how ignorant I was.
the first step is object oriented analysis - its aim is to identify the objects that make up a system and how they interact; given this knowledge you can then specify the behavior of the object (the interface methods) and then the internals (what are the required data members of an object)
The design process produces a number of diagrams - these are tools that are supposed to help with working out the details of the system :
first come a set of 'use cases' - a use case is a verbal description of a scenario that is implemented by the system (one is supposed to pick the most substantial ones); these are then used to identify the main actors and concepts which are supposed to map to the classes of a system. This understanding is then refined by working out 'object interaction diagrams' 'class diagrams' and 'sequence diagrams' sometimes state charts are used to visual state machines - these diagrams are tools to gain an even better understanding of the system, as a result you have a sufficient understanding of the system to write the class header files/class definitions. There are no fixed rules which one of these diagrams come first, these are used as appropriate.
i found the following book very useful :
OBJECT-ORIENTED ANALYSIS AND DESIGN With applications (second edition) by Grady Booch
the book goes through the process of designing several example systems step by step (i think it is enough to read the design process for these example systems); One minor problem is that the notation used in this book is a bit dated : modern practice is to use the UML notation for diagrams, however the book still uses the older Booch notation. The strong point of the book is that it is always explaining each concept by working through concrete examples.
There are some preliminary steps:
Understand OOD (in general)
Understand the problem/application domain (the functional specification)
Have a high-level/architectural design: know what O/S, libraries, frameworks etc. you can use
I then use a mixture of top-down and bottom-up development:
Top-down: decide what components and what APIs (object interfaces) I would like to have in order to implement the application (and then, develope those API)
Bottom-up: decide how to add new functionality to existing APIs (object interfaces), by adding new methods and new types of object (and sometimes splitting a large object into several smaller objects).
The first step of OOD are the OOD principles. Check out The Principles of OOD.
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 5 years ago.
Improve this question
I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?
Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.
A good documentation MUST have:
datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
examples. Sometimes they are more important than all the rest
I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...
Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?
What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.
Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:
Very easy jump to docs from the API.
Well formatted and the code snippets
you would want to copy and paste
(like method signatures) stand out.
Links to projects with sample code
right from the docs.
Automated document refresh mechanism,
but by default docs are all local to
start (so you can live with a flaky
internet connection).
Easy way to switch between variants
of documentation (to see different
versions of the OS), and also select
which sets of documentation to run
searches against.
An overview section explains what the
class is for, followed by a section
breaking out methods grouped by
purpose (methods to create and
object, methods to query for data,
methods to work with type
conversions, etc), followed by the
detailed method explanations.
I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.
A good API will have the following characteristics:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.
I personally believe a perfect example of good documentation is PHP's documentation:
For an example:
http://www.php.net/manual/en/function.fopen.php
I think effective documentation includes:
Parameter listing
(Useful) description of the parameter
If they parameters are a string, list
out and EXPLAIN every possible
possible parameter
Return values on both successful
execution and non-successful
execution
Any exceptions/errors it can raise
Examples (THE MOST IMPORTANT imo)
Optionally:
Changelog
Notes/Examples from other users
Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.
What is think is an example of a alright documentation is Python's:
http://docs.python.org/py3k/library/array.html
It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.
Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.
It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.
The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.
Answer the question: "how do I do X with Y?" You may know the answer. I don't.
My main criteria is - tell me everything I need to know and everything I'll ever want to know.
QT has pretty decent docs:
http://doc.qt.digia.com/4.5/index.html
Win32 MSDN is also pretty good although it didn't age well.
The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?
I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.
I think that a good API document needs to clearly explain:
What problem this API solves
When you should use it
When you shouldn't use it
Actual code showing "best practice" usage of the API
Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.
Just a few thoughts...
Examples - win32 API documentation is better than iPhone's because of:
(short) code examples
I vote for any API doc with small and make-sense examples
Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes
good API is solving real world problems and there should be some meaningful examples
Don't auto-gen doc
documentation should not be done during writing code (or by the same guy)
doc is for a stranger, whom the programmers usually don't care of
Avoid ___V2 version of API
but it's not a doc issue
Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?
Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.
#author:
Who wrote this? Who's proud of it? Who should be ashamed of their work?
Interface level documentation tells me:
what should this do?
what will it return?
Implementation level documentation tells me:
how does it do it? what kind of algorithm? what sort of system load?
what conditions might cause a problem? will null input cause an issue? are negative numbers okay?
Class level documentation tells me:
what goes here? what kind of methods should I expect to find?
what does this class represent?
#Deprecated tells me:
why is this planned for removal?
when is it expected to be removed?
what is the suggested replacement?
If something is final:
why didn't you want me to extend this?
If something is static:
remind me in the class level doc, at least implicitly.
In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.
As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.
First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.
The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.
Good documentation should have at least the following:
When an argument has additional limitations beyond its type, they need to be fully specified.
Description of the [required] state of an object before calling the method.
Description of the state of an object after calling the method.
Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.
In addition, the following are useful:
Description of the state of an object if an exception is thrown by the method.
Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
Example usage.
Based on this:
An example of great documentation is the MSDN library.
To be fair, the online version of this does suffer from difficulty of navigation in cases.
An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
IMO examples are the best documentation.
I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.
What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.
One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?
This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.
I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.
i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!
I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?
Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:
Unity Application Block (Go to the Download section for the CHM)
All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.
The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.
Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.
I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.
Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).
Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.
I would definitely recommend watching Josh Bloch's presentation about this:
http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw
This covers not only what you're looking for but much more.
Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.
The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.
API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.
Most things about good documentation have already been mentioned, but I think there is one aspect about the JavaDoc way of API documentation that is lacking: making it easy to distinguish between the usage scenarios of all the different classes and interfaces, especially distinguishing between classes that should be used by a library client and those that should not.
Often, JavaDoc is pretty much all you get and usually there is no package documentation page. One is then confronted with a list of hundreds or even more of classes: where and how to start? What are typical ways of using the library?
It would be good if there were conventions of how to make it easy to provide this information as part of JavaDoc. Then the generated API documentation could allow for different views for different groups of people -- at a minimum two groups: those who implement the library and those who use it.
I find Google APIs a beautiful example of Good documentation API.
They have:
Bird's eyes view of the entire APIs structure
Overviews of the main features of the single API
Nice and colored examples for a quick feedback
Detailed references
A blog that keep you updated
A google groups that documents problems and solutions
Videos
FAQ
Articles
Presentations
Code Playground
A search engine to crawl inside a pile of documentation
That's it!
When I play with google APIs documentation site, I feel at home.
Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:
http://www.doxygen.nl/results.html
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
So I'm working on this class that's supposed to request help documentation from a vendor through a web service. I try to name it DocumentRetriever, VendorDocRequester, DocGetter, but they just don't sound right. I ended up browsing through dictionary.com for half an hour trying to come up with an adequate word.
Start programming with bad names is like having a very bad hair day in the morning, the rest of the day goes downhill from there. Feel me?
What you are doing now is fine, and I highly recommend you stick with your current syntax, being:
context + verb + how
I use this method to name functions/methods, SQL stored procs, etc. By keeping with this syntax, it will keep your Intellisense/Code Panes much more neat. So you want EmployeeGetByID() EmployeeAdd(), EmployeeDeleteByID(). When you use a more grammatically correct syntax such as GetEmployee(), AddEmployee() you'll see that this gets really messy if you have multiple Gets in the same class as unrelated things will be grouped together.
I akin this to naming files with dates, you want to say 2009-01-07.log not 1-7-2009.log because after you have a bunch of them, the order becomes totally useless.
One lesson I have learned, is that if you can't find a name for a class, there is almost always something wrong with that class:
you don't need it
it does too much
A good naming convention should minimize the number of possible names you can use for any given variable, class, method, or function. If there is only one possible name, you'll never have trouble remembering it.
For functions and for singleton classes, I scrutinize the function to see if its basic function is to transform one kind of thing into another kind of thing. I'm using that term very loosely, but you'll discover that a HUGE number of functions that you write essentially take something in one form and produce something in another form.
In your case it sounds like your class transforms a Url into a Document. It's a little bit weird to think of it that way, but perfectly correct, and when you start looking for this pattern, you'll see it everywhere.
When I find this pattern, I always name the function xFromy.
Since your function transforms a Url into a Document, I would name it
DocumentFromUrl
This pattern is remarkably common. For example:
atoi -> IntFromString
GetWindowWidth -> WidthInPixelsFromHwnd // or DxFromWnd if you like Hungarian
CreateProcess -> ProcessFromCommandLine
You could also use UrlToDocument if you're more comfortable with that order. Whether you say xFromy or yTox is probably a matter of taste, but I prefer the From order because that way the beginning of the function name already tells you what type it returns.
Pick one convention and stick to it. If you are careful to use the same names as your class names in your xFromy functions, it'll be a lot easier to remember what names you used. Of course, this pattern doesn't work for everything, but it does work where you're writing code that can be thought of as "functional."
Sometimes there isn't a good name for a class or method, it happens to us all. Often times, however, the inability to come up with a name may be a hint to something wrong with your design. Does your method have too many responsibilities? Does your class encapsulate a coherent idea?
Thread 1:
function programming_job(){
while (i make classes){
Give each class a name quickly; always fairly long and descriptive.
Implement and test each class to see what they really are.
while (not satisfied){
Re-visit each class and make small adjustments
}
}
}
Thread 2:
while(true){
if (any code smells bad){
rework, rename until at least somewhat better
}
}
There's no Thread.sleep(...) anywhere here.
I do spend a lot of time as well worrying about the names of anything that can be given a name when I am programming. I'd say it pays off very well though. Sometimes when I am stuck I leave it for a while and during a coffee break I ask around a bit if someone has a good suggestion.
For your class I'd suggest VendorHelpDocRequester.
The book Code Complete by Steve Mcconnell has a nice chapter on naming variables/classes/functions/...
I think this is a side effect.
It's not the actual naming that's hard. What's hard is that the process of naming makes you face the horrible fact that you have no idea what the hell you're doing.
I actually just heard this quote yesterday, through the Signal vs. Noise blog at 37Signals, and I certainly agree with it:
"There are only two hard things in Computer Science: cache invalidation and naming things."
— Phil Karlton
It's good that it's difficult. It's forcing you to think about the problem, and what the class is actually supposed to do. Good names can help lead to good design.
Agreed. I like to keep my type names and variables as descriptive as possible without being too horrendously long, but sometimes there's just a certain concept that you can't find a good word for.
In that case, it always helps me to ask a coworker for input - even if they don't ultimately help, it usually helps me to at least explain it out loud and get my wheels turning.
I was just writing on naming conventions last month: http://caseysoftware.com/blog/useful-naming-conventions
The gist of it:
verbAdjectiveNounStructure - with Structure and Adjective as optional parts
For verbs, I stick to action verbs: save, delete, notify, update, or generate. Once in a while, I use "process" but only to specifically refer to queues or work backlogs.
For nouns, I use the class or object being interacted with. In web2project, this is often Tasks or Projects. If it's Javascript interacting with the page, it might be body or table. The point is that the code clearly describes the object it's interacting with.
The structure is optional because it's unique to the situation. A listing screen might request a List or an Array. One of the core functions used in the Project List for web2project is simply getProjectList. It doesn't modify the underlying data, just the representation of the data.
The adjectives are something else entirely. They are used as modifiers to the noun. Something as simple as getOpenProjects might be easily implemented with a getProjects and a switch parameter, but this tends to generate methods which require quite a bit of understanding of the underlying data and/or structure of the object... not necessarily something you want to encourage. By having more explicit and specific functions, you can completely wrap and hide the implementation from the code using it. Isn't that one of the points of OO?
More so than just naming a class, creating an appropriate package structure can be a difficult but rewarding challenge. You need to consider separating the concerns of your modules and how they relate to the vision of the application.
Consider the layout of your app now:
App
VendorDocRequester (read from web service and provide data)
VendorDocViewer (use requester to provide vendor docs)
I would venture to guess that there's a lot going on inside a few classes. If you were to refactor this into a more MVC-ified approach, and allow small classes to handle individual duties, you might end up with something like:
App
VendorDocs
Model
Document (plain object that holds data)
WebServiceConsumer (deal with nitty gritty in web service)
Controller
DatabaseAdapter (handle persistance using ORM or other method)
WebServiceAdapter (utilize Consumer to grab a Document and stick it in database)
View
HelpViewer (use DBAdapter to spit out the documention)
Then your class names rely on the namespace to provide full context. The classes themselves can be inherently related to application without needing to explicitly say so. Class names are simpler and easier to define as a result!
One other very important suggestion: please do yourself a favor and pick up a copy of Head First Design Patterns. It's a fantastic, easy-reading book that will help you organize your application and write better code. Appreciating design patterns will help you to understanding that many of the problems you encounter have already been solved, and you'll be able to incorporate the solutions into your code.
Leo Brodie, in his book "Thinking Forth", wrote that the most difficult task for a programmer was naming things well, and he stated that the most important programming tool is a thesaurus.
Try using the thesaurus at http://thesaurus.reference.com/.
Beyond that, don't use Hungarian Notation EVER, avoid abbreviations, and be consistent.
Best wishes.
In short:
I agree that good names are important, but I don't think you have to find them before implementing at all costs.
Of course its better to have a good name right from the start. But if you can't come up with one in 2 minutes, renaming later will cost less time and is the right choice from a productivity point of view.
Long:
Generally it's often not worth to think too long about a name before implementing. If you implement your class, naming it "Foo" or "Dsnfdkgx", while implementing you see what you should have named it.
Especially with Java+Eclipse, renaming things is no pain at all, as it carefully handles all references in all classes, warns you of name collisions, etc. And as long as the class is not yet in the version control repository, I don't think there's anything wrong with renaming it 5 times.
Basically, it's a question of how you think about refactoring. Personally, I like it, though it annoys my team mates sometimes, as they believe in never touch a running system. And from everything you can refactor, changing names is one of the most harmless things you can do.
Why not HelpDocumentServiceClient kind of a mouthful, or HelpDocumentClient...it doesn't matter it's a vendor the point is it's a client to a webservice that deals with Help documents.
And yes naming is hard.
There is only one sensible name for that class:
HelpRequest
Don't let the implementation details distract you from the meaning.
Invest in a good refactoring tool!
I stick to basics: VerbNoun(arguments). Examples: GetDoc(docID).
There's no need to get fancy. It will be easy to understand a year from now, whether it's you or someone else.
For me I don't care how long a method or class name is as long as its descriptive and in the correct library. Long gone are the days where you should remember where each part of the API resides.
Intelisense exists for all major languages. Therefore when using a 3rd party API I like to use its intelisense for the documentation as opposed to using the 'actual' documentation.
With that in mind I am fine to create a method name such as
StevesPostOnMethodNamesBeingLongOrShort
Long - but so what. Who doesnt use 24inch screens these days!
I have to agree that naming is an art. It gets a little easier if your class is following a certain "desigh pattern" (factory etc).
This is one of the reasons to have a coding standard. Having a standard tends to assist coming up with names when required. It helps free up your mind to use for other more interesting things! (-:
I'd recommend reading the relevant chapter of Steve McConnell's Code Complete (Amazon link) which goes into several rules to assist readability and even maintainability.
HTH
cheers,
Rob
Nope, debugging is the most difficult thing thing for me! :-)
DocumentFetcher? It's hard to say without context.
It can help to act like a mathematician and borrow/invent a lexicon for your domain as you go: settle on short plain words that suggest the concept without spelling it out every time. Too often I see long latinate phrases that get turned into acronyms, making you need a dictionary for the acronyms anyway.
The language you use to describe the problem, is the language you should use for the variables, methods, objects, classes, etc. Loosely, nouns match objects and verbs match methods. If you're missing words to describe the problem, you're also missing a full understanding (specification) of the problem.
If it's just choosing between a set of names, then it should be driven by the conventions you are using to build the system. If you've come to a new spot, uncovered by previous conventions, then it's always worth spending some effort on trying extend them (properly, consistently) to cover this new case.
If in doubt, sleep on it, and pick the first most obvious name, the next morning :-)
If you wake up one day and realize you were wrong, then change it right away.
Paul.
BTW: Document.fetch() is pretty obvious.
I find I have the most trouble in local variables. For example, I want to create an object of type DocGetter. So I know it's a DocGetter. Why do I need to give it another name? I usually end up giving it a name like dg (for DocGetter) or temp or something equally nondescriptive.
Don't forget design patterns (not just the GoF ones) are a good way of providing a common vocabulary and their names should be used whenever one fits the situation. That will even help newcomers that are familiar with the nomenclature to quickly understand the architecture. Is this class you're working on supposed to act like a Proxy, or even a Façade ?
Shouldn't the vendor documentation be the object? I mean, that one is tangible, and not just as some anthropomorphization of a part of your program. So, you might have a VendorDocumentation class with a constructor that fetches the information. I think that if a class name contains a verb, often something has gone wrong.
I definitely feel you. And I feel your pain. Every name I think of just seems rubbish to me. It all seems so generic and I want to eventually learn how to inject a bit of flair and creativity into my names, making them really reflect what they describe.
One suggestion I have is to consult a Thesaurus. Word has a good one, as does Mac OS X. That can really help me get my head out of the clouds and gives me a good starting place as well as some inspiration.
If the name would explain itself to a lay programmer then there's probably no need to change it.