Related
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.
When I'm writing it?
After I got a part done (Single class/function/if-elses)?
After I got the whole thing working?
The short answer
The short answer is anytime something is non-obvious relative to whose going to be reading it. If its code that is still in flux so you are the only consumer, just comments for you (hours and days). Ready to check in for others to try out - comments for you and your team (days and weeks, possibly months). Ready for wide release - comments for the immediate and future public (months and years). You have to think of comments as tools, not documentation.
The long answer:
When I'm writing it? - Yes
After I got a part done (Single class/function/if-elses)? - Yes
After I got the whole thing working? - Yes
When I'm writing it? - Yes
Drop comments anytime you hit a place where the code isn't immediately clear. For example, describe the class when the class name isn't clear or could be interpreted too widely. Another example is if I'm about to write a non-obvious code block, I'll first add a comment reminding me of what I want/need. Or if I just added some code and I immediately realized there was a gotcha in there, drop a comment to remind yourself. These comments are implementor comments, less to help future maintainers, but rather to help yourself in the coding process.
Drop FIXME - explanation and TODO explanations reminders as you go.
Code is still in flux, so I'm not yet documenting every and all method and parameter.
After I got a part done (Single class/function/if-elses)? - Yes
When I'm reasonably done with a method or class, now is the time to review it. Along with checking scopes of methods, ordering methods, and other code cleanup to improve understandability, now's the time to begin to standardize it against your team standards. Consider what comments are need based on the audience it will be released to (future you is part of the audience too!) Does the class have a header block? Are there non-obvious conditions under which this method should not be called? Does this parameter have any conditions on it, e.g. should not be null?
Check the FIXME and TODO items - still valid? Any you should address now before moving on?
These are still notes for you and your team, but the beginnings of standardized notes for future maintainers.
After I got the whole thing working? - Yes
Now is the time to review everything and finalize comments against your standards.
All FIXME and TODO items addressed (fixed or captured as known issue)?
These notes now are for future maintainers.
Now the dirty little secret
More is not always better. Like unit tests, you have to balance use of your tools weighing costs vs benefits. The fact is that a coder can only type so many physical lines per hour - what percent should be comments? A low percentage means I've got a lot of code, but its confusing and difficult to understand and use correctly. A high percentage means that, in an hour when someone changes a method signature or redefines an interface, all the time is spent fully commenting every parameters of those methods just got trashed.
Find the right percentage based on the stability of the code, how long it will live, and how widely it will be released. Not stable yet - minimal comments to help you and your team. Stable and ready for project - fully commented. Public release? - fully commented (check again!) with copyrights (if applicable). As you gain experience, adjust the percentage.
You should never "add" comments - they are not additions. Comments are part of the code - you use them when you need them. Asking when you should add them is like asking when you should add functions or classes. Though thinking about it, I remember doing a program advice slot at university I worked for where one of the students came in with about 1000 lines of Pascal, with no functions. When I queried why he hadn't used functions, his response was "I'll add them later, once I've got it working."
This is subjective, but sometimes it's better to add them before the actual code, eg. when you implement an algorithm that has clearly defined steps. By that way it's harder to miss steps.
This is a matter of style. Personally, I like writing comments during the coding, not after. Because it I leave it to after, I usually get lazy and don't write them at all. That said, sometimes it's useful to go over a completed piece of code, figure out what isn't obvious from the code itself and document it. In particular, the parts where assumptions are made.
I would suggest writing comments whenever you edit any code, while you are editing it. According to Robert C. Martin in Clean Code, a disadvantage of comments is that the code can change without the comments being updated, making the comments not only useless, but dangerous. To reduce this problem, if you must use comments (because you are unable to express yourself in the code itself), make sure you update them every time you update the code.
You should try writing comments BEFORE you write any code. eg
public string getCurrentUserName() {
//init user database repository
//retrieve logged in user
//return name if a user is logged in, otherwise return null
}
Writing comments before you code, helps you learn how to structure your code without actually coding it and realising that you should have done it another way. It's also a good way to quickly visualise a clean solution to a complex problem without getting bogged down in implementation. It's also good because if you get interrupted, when you come back to your work you can go straight back to it, as opposed to refigure out what you have done and what you need to do next.
Not suited to all situations, but often a good option!
A disadvantage of adding comments later is that a lot of times that will simply not be done, due to lazyness, other tasks, etc.
If you find you can always go back and add the appropriate comments without any problem, then by all means do so, but otherwise making a conscious effort to add them as you're coding or before you code a section may be a way to ensure that you don't leave the code uncommented.
Put a comment ANYWHERE the programmer reading your code, may generate a WTF moment.
If you find yourself commenting every line, perhaps you need to take a look at trying to improve your code with simpler, more elegant statements.
Comments should reflect why you are doing the things the way you do, not what it does. Most of the time the one reading your code can read what it does.
You should explain the the things one cannot reduce from the code.
I tend to put basic comments as I'm going, just to remind myself what I was thinking at the time when I wrote it (i.e. why I wrote it that way). I do this especially if it's code that looks like it might be wrong but is actually right, or code that has an inherent race condition that I don't care about, or code that might not be optimal but is a quick way to get something working, so that even ten minutes later when I go back and look at it I can see that I've thought about the problem already and don't have to waste any brain cycles on it.
When the code is more complete, I'll often go back and review the comments I've written and then have a think about whether I still think the decisions made are reasonable, and whether things could be done better. I'll also often expand the basic comment into a longer comment that's more useful for other people when they come to maintain the code; I usually save comment expansion to the end because a lot of the time basic comments just get deleted during refactoring, so writing a long comment is a waste of time until you know you're going to keep it.
In a nutshell, write basic comments as you go along, and then improve them as your code becomes more stable.
Oh, and also, any time you review a bit of existing code and you're struck with a WTF?! moment but then realise the code is actually decent, put a comment in to save yourself and the next person time when they look at it in the future.
The question should be, when do I add code to my comments?
My practice is to write out the functionality of a module/object/function as a series of comments. Not comments like "add one to counter". Higher level comments like
"sort list by account number". Detailed comments are pretty much redundant with the code. So I avoid those unless I'm writing a very tricky algorithm.
Once I have the functionality "designed" in comments, I act like a human compiler and
add in the code after each line of comments.
Give it a try and let us know how it works!
Personally, I tend to write comments to summarise code where necessary - often before I write the code, as well as to save WTFs. I treat them very exactly as notes - of things to do, things that I have done this way, or will do this way, and as such they are put in when and where I feel the need for them.
Before you forget what specification and design the code is required to implement.
Before you forget that some unfortunate coder will have to read it later on.
Before you forget that the unfortunate coder could well be you.
When you do something non-trivial, as you're writing it.
You gave a lot of cases in your question. I think it depends on what you're doing at the time.
If you're writing a function or a class, comments are a way to declare what's supposed to happen with the function. Things like input variables, output type, special behavior, exceptions, etc. IMHO that kind of comment should be written before the actual code is started, in your "code design" phase. Most languages have packages which process those kind of comments into documentation (javadoc, epydoc, POD, etc, so that stuff will be read by users.
If you're making a bit of code work, I think it's OK to wait until you've got it working to put in a comment triumphantly describing your working solution. That kind of comment is only going to get read by a code reviewer.
Then, as others have said, you want to avoid WTF moments, by yourself or others. I once got an attaboy for a comment I made once in an open-source project. The comment was "Yes, I really do want = and not == on that line."
A. when you decide an arbitrary decion that would be difficult to re-understand.
B. Every thing that you feel that you should remember while writting the code
C. in the beginning of a program explain the logic and use
Advice - instead of commenting a lot use long names for functions and vars that realy explain what the function does or what the variable stands for.
Mostly at time when you write that code. You can go there after the function/block/whatever is done and organize your comments on fresh mind. Most of the stuff we write while coding are not meaningful later.
Early on in my career I added comments to nearly every line of code, as you may do perhaps in an ASM program. As time went by I ran into many of the problems mentioned here. It was a bear to maintain which resulted in not updating comments and then they become stale at best, usually moldy.
I feel that the # of comments should reflect how complex or non-obvious the code itself is. In a more challenging environment, such as ASM, you will probably need more comments to understand what is going on. In more modern languages like C# you shouldn't need a whole lot of comments in most cases.
Generally I use tools that evaluate the complexity of my methods in C#. Those that are high on the complexity scale first get refactored. Then when I'm satisfied with the complexity remaining and I still have some code that is not obvious, or even more important, seems obvious but does something different, then I tack a comment on it.
I add comments while writing any code that is not easily understandable. I find that if I don't do it immediately then it gets forgotten. I (or more likely someone else) then spends more time figuring what I did than it would have taken to write the comment.
To be more precise, commenting immediately after the code is written is the best avenue to ensure comments actually get written.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a tool, library or favorite off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 8 years ago.
Improve this question
We are developing a desktop application.We are writing tutorials for users in a wiki.I was looking for some guidance ..good practices when writing such tutorials.
regards
I think some basic rules are ok
include as many screenshots as you can
don't use too much technical wording
structure your pages/documents that it is easy to navigate inside
don't make the user looks stupid, i.e. way of writing that would say the user is not capable of doing anything
Also it could be a good idea if you make your wiki and ask one typical user to review it with you. Getting the opinion of the user would probably show you million of things you have forgotten.
Have a FAQ
Tips and Tricks Section.
Have short videos about "How to..."
A few tips for technical documents:
1- Assume everyone reading the document is the dumbest person you've ever met who has never seen a computer in their entire life.
2- Don't skip a single step. Even if it's clicking a well-known button, etc. If your instruction doesn't start with "click" or "type", it's not granular enough.
3- There are never too many screenshots... unless you can't read the text between them, or fail to notice it entirely. Leave enough spaces between screenshots and text, and make the text one size larger if need be.
4- Do it yourself, multiple times. Make others follow your directions. Make your grandmother follow them. If she can, your manager probably can. Maybe.
Figure out the key features that users will use most often and provide a cheat sheat. Download any one refcards from dzone.com as an example.
I think the best tutorials are those that guide the students in an incremental, step-wise manner. Clearly describe prerequisites at the top and tell the readers 1, 2, 3 this is what you have to do.
Choose your tasks thoughtfully (and stick to them). Each tutorial should cover a single task and stay focused on the goal throughout, with only the briefest digressions to introduce new terms or concepts. Start with the very first step a user needs to take to do something useful with the software. With a well designed app, a sequence of introductory tutorials is likely to start with a very short, simple one ("Creating a New Project") and proceed through intermediate ("Importing INTERCAL-72 Files") to advanced topics ("Customizing the Compiler Toolchain") so that the tutorials become more involved as the user becomes more involved with the app.
Use numbered lists. Describe specific procedures that can be followed by anyone who can read.
Use consistent styles for program and interaction elements, like bold text for buttons and menu items and monospace fonts for user input. The specific styles you choose matter less than their consistent application. If we're talking Windows apps, the Microsoft Manual of Style for Technical Publications might come in handy.
Verify your procedures relentlessly. If a user needs a tutorial to figure out how to use the application, she's probably already frustrated. If she follows it to the letter and it doesn't work, everyone's a lot worse off, including you and your support rep.
Use screenshots as signposts. Include one screenshot of each window and dialog box referenced by the procedure. Don't label them or otherwise doll them up. They're there to provide visual reinforcement that the user is following the procedure correctly and getting to the right places.
Respect different learning styles. Keep in mind that most people are visual and/or auditory learners, so text isn't the best way to reach them. In practice, that means screenshot videos with voiceover. The written tutorial is the script.
make sure your app is intuitive first. then when your sure it is, make it more intuitive.
see :
http://www.discoapp.com/
http://www.utorrent.com/
http://handbrake.fr/
http://www.nethack.org/
dont see:
http://www.adobe.com/
Windows songsmith
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 3 years ago.
Improve this question
I would like to know your experience when you need to take over somebody else's software project - more so when the original software developer has already resigned.
The most success that we've had with that is to "wiki" everything. During the notice period ask the leaving developer to help you document everything in the team/company wiki and see if you can do code reviews with him/her and add comments to the code while doing the reviews that explain sections. Best for the "taking over" developer to write the comments in the code under the supervision of the leaver.
Cases where original devs leaved before handing over the project are always the most interesting: you're stuck with a codebase in an unknown state. What I always find intriguing is how the new devs often do their utmost best to comment on how badly designed the code is: they forget about the constraints the old devs might have been under, the shortcuts they might have been forced to make. The saying is always Old dev == bad dev. What do you people think:
I would even call this out as an official bad practice: bad-mouthing the ones who have been before us.
I try to take as much a pragmatic approach as possible: learn the codebase, wander around a bit. Try to understand the relation between requirements and code, even is there is no clear initial relationship at all. There will always be the "aha moment" when you realise why they did something was done this way or that. If you're still convinced something is implemented the wrong way, do your refactorings if possible. And isolate the pieces of code you cannot change: unit test them by using a mocking framework.
Hail to the maintenance developer.
I once joined a team which has been handed over a pile of steaming crap from outsourcing. The original project - a multimedia content manager based on Java, Struts, Hibernate|Oracle - was well structured (it seems like it was the work of a couple of people, pair programming, wise use of design patterns, some unit testing). Then someone else inherited the project and endlessly copy-pasted features, loosened the business rules, patched, branched until it became a huge spaghetti monster with fine crafted piece of codes like:
List<Stuff> stuff = null;
if (LOG.isDebugEnabled())
{
stuff = findStuff();
LOG.debug("Yeah, I'm a smart guy!");
for (Stuff stu : stuff)
{
LOG.debug("I've got this stuff: " + stu);
}
}
methodThatUsesStuff(stuff);
hidden amongst the other brilliant ingenuity.
I tamed the beast via patient refactoring (extracting methods and classes more of the times), commenting the code from time to time, reorganizing everything till the codebase shrunk by 30%, getting more and more manageable over time.
I had to take over someone else’s code of different degrees of quality on several occasions. Hence the tips:
Make effort to take structured notes of any piece of significant information from minute one: names of stakeholders, business rules, code and document locations etc. It is best to dedicate a fresh spiral notebook, so you could tear pages out if you had to.
Make use of one of the better free indexing and desktop search tools available on the market (Google Desktop Search, MS Windows Search will do). Add all document, e-mail, code locations to it.
Before developing anything do document analysis: find everything you can get you hands on electronically on network and printed out docs, make effort of simply reading it. There is amazingly much of useful information even within unfinished drafts.
Mind map the code, architecture etc as you go.
With lesser documented and maintained systems you inevitably will have moments of despair that are likely to push you into procrastination mode. Especially during your first days or week when amount of new information your mind has to digest is overwhelming. At these times it is nice to have someone to remind you (or just do it yourself) to take it easy, concentrate on important things first and revert to making smaller steps in trying to gain understanding instead of trying to leap forward.
Keep taking notes, making diagrams, drawing rich pictures, mind mapping. It really helps to digest the copious amounts of new information, mostly disorganised.
Hei, good luck!
We actually have a specified set of "Deliverables" that has to be present for us to take over a project.
If we have the chance we try to push in one of our folks within the group developing the project at first. That way we get some firsthand knowledgde before our group takes over the code. (in the line of what #Guy wrote)
That being said, the most important part for me would be:
Some kind og highlevel overview(drawing?) of what the code do.
Easy access to ask questions of the people who actually wrote the code
This for me is alpha omega when taking over code and projects
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 4 years ago.
Improve this question
I'm building Desktop Software for over 10 years now, mostly it's simple Data-Input Software. My problem is, it's always looking the same: A Treeview on the Left and a lot of Text/Data Fields to the right, depending on the type of data currently is worked on. Are there any fresh ideas how such software nowadays should look like?
For further clarification:
It's very hierarchical data, mostly for electronic devices. There are elements of data which provide static settings for the device and there are parts which describe some sort of 'Program' for the device. There are a lot (more than 30) of different input masks. Of course i use combo boxes and Up/Down Entry Fields.
Having all of your software look the same thing is a good thing. One of the best ways to make it easy for people to use your software is to make it look exactly the same as other software your users already know how to use.
There are basically two common strategies for how to handle entry of a lot of data. The first is to have lots of data entry fields on one page. The next is to have only a few data entry fields but a lot of pages in a sort of wizard-style interface. Expert users find the latter much slower to use, as do users who are entering data over and over again. However, the wizard style interface is less confusing for newer users since it offers fewer elements at once and tends to provide more detail on them.
I do suggest replacing as many text fields as possible with auto-complete-based combo-boxes. This allows users to enter data exactly the same as with text-boxes, but also allows users to save typing by hitting the down key to scroll through choices after typing part of the data in.
Providing more detail on what data is being entered would probably yield more specific answers.
I'd also answer with a question, which is to ask what your motivation for considering a change is? Like the other posters, I'd agree that there is some value in consistency, but there's also a strong value in not ignoring niggles-in-the-back-of-the-mind feelings you have. Maybe you have a sense that your users aren't as productive as you'd like them to be, or you've heard feedback to that effect from your customers, or you're just looking to add some innovation for your own interest. Scratching itches is a good trait in a developer, in my view.
One thing I'd advocate would be a detailed user study. How much do you know about what your users do with the interfaces you create? Do you know the key tasks, the overall workflow? Would you know if one task regularly consumed 60% of your users' time, or if there was a task that was only performed once a month? Getting a good sense of what the users actually do (and not what they say they do) is a great place to start thinking about what changes might be worthwhile, especially if you can refactor the task to get a qualitatively different user experience.
A couple of specific alternative designs you might like to include in re-visioning the UI might be be facet browsing (works well for searching and exploring in hierarchies), or building a database of defaults / past responses so that text boxes can use predictive completion. However, I think my starting point would be the user study.
Ian
If it works...
Depending on what you've got happening with the data (that is, is it hierarchical, or fairly flat), you might want to try a tab-based metaphor, or perhaps the "Outlook-style", with a sidebar showing the sections of an application. One other notion I've played with lately is the "Object desktop" that I first saw proposed by Scott Ambler (Building Object Applications That Work). In this, you can display collections of items, or the user can "peel off" individual records for easy access.
Your information is not enough to really suggest you an interface alternative. However, may I answer your question with a question? Why do you think you have to change it? Has your customer complained? If not, it looks like your customer is happy with the way the software works right now, thus I wouldn't change it. If your customer complains about it, he'll most likely not just say "It's bad", he will say "Why can't it look like ..." and this will give you an idea how to change it.
I once had to re-design a very outdated goods management system. The old one was written for a now dead database system, still running in MS-DOS. The customer suggested I should create a prototype how this re-implementation might look like and then he'll decide if I get that job or not. I replaced the old, dead database with a modern MySQL database, I replaced the problematic shared peer access with a client server approach and I chose to rewrite the UI in Java, since different OSes were used and this had the smallest porting costs. So far the concept seemed good, the customer liked it. However, when he asked his employees what they think about it, they asked "So far it's great, but we have one question: Why doesn't it look like the old one?". Actually, it turned out that even with all the modern technologies, they wanted the interface to exactly look and being operated like the old one. So I had to re-build a 1986 usability nightmare MS-DOS UI in Java, because no other UI was accepted.
For me it is more about a clean, usable, logical design than anything else. If your program makes sense to the user, isn't clunky and works as advertised, then everything else UI related is essentially just like painting the house. I've sometimes rolled out a new version of a program with essentially the same controls that are skinned differently.
There's a reason that you've probably chosen the tree view - because it probably makes really good sense to do so. There are different containers and controls available in the various UI libraries, depending on the language, but I tend to stick with the familiar because the user probably gets how a tree control works and how a combobox works.
A user interface needs to be usable, just don't do the misstake to change to something working to something fancy-schmancy just because it looks better (been down that road)...
Make sure that added
widgets/controls really add a business value
Make sure that the added
widgets/controls do not mess up your
architecture (too much) and makes
the application harder to
manage/maintain
Try to keep platform standards on
how to do things (for example the Vista ux guidelines)
:)
//W
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 3 years ago.
Improve this question
I've seen different program managers write specs in different format. Almost every one has had his/her own style of writing a spec.
On one hand are those wordy documents which given to a programmer are likely to cause him/her missing a few things. I personally dread the word documents spec...I think its because of my reading style...I am always speed reading things which I think will cause me to miss out on key points.
On the other hand, I have seen this innovative specs written in Excel by one of our clients. The way he used to write the spec was kind of create a mock application in Excel and use some VBA to mock it. He would do things like on button click where should the form go or what action should it perform (in comments).
On data form, he would display a form in cells and on each data entry cell he would comment on what valid values are, what validation should it perform etc.
I think that using this technique, it was less likely to miss out on things that needed to be done. Also, it was much easier to unit test it for the developer. The tester too had a better understanding of the system as it 'performed' before actually being written.
Visio is another tool to do screen design but I still think Excel has a better edge over it considering its VBA support and its functions.
Do you think this should become a more popular way of writing spec? I know it involves a bit of extra work on part of project manager(or whoever is writing the spec) but the payoff is huge...I myself could see a lot of productivity gain from using it. And if there are any better formats of specs that would actually help programmer.
Joel on Software is particularly good at these and has some good articles about the subject...
A specific case: the write-up and the spec.
Two approaches have worked well for me.
One is the "working prototype" which you sort of described in your question. In my experience, the company contracted a user interface expert to create fully functional HTML mocks. The data on the page was static, but it allowed for developers and management to see and play with a "functional" version of the site. All that was left to do was replace the static data on the pages with dynamic content - this prototype was our spec for the initial version of our product. The designer even included detailed explanation of some subtle behavior in popup dialogs that would appear when hovering over mock links. It worked well for our team.
On a subsequent project, we didn't have the luxury of the UI expert, but we used similar approach. We used a wiki to mock a version of the site. We created links between the functional aspects of the system and documented each piece of functionality in detail. Each piece of functionality could, in turn, link to detailed design and architecture decisions. We also used to wiki to hold our to list feature list for each release (which became our release notes). These documents linked back to the detailed feature page. The wiki became a living document - describing our releases and evolution of our system in great detail. It was an invaluable resource.
I prefer the wiki to the working prototype because it's more easily extensible - growing and becoming more valuable as your system evolves.
I think you may have a look about Test-Driven Requirements, which is a technique to make executable specifications.
There are some great tools like FIT, Fitnesse, GreenPepper or Concordion for that purpose.
One of the Microsoft Press books has excellent examples of various documents, including an SRS (which I think is what you are talking about). It might be one of the requirements books by Weigert (I think that's his name, I'm blanking on it right now). I've seen US government organizations use that as a template, and from my three work experiences with the government, they like to make their own whereever they can, so if they are reusing it, it must be good.
Also - a spec should contain NO CODE, in my opinion. It should focus on what the system must do, should do, and can not do using text and diagrams.