We're developing a website that will try to have a lot of interesting quality content and hopefully will attract a big, vibrant community. So, we expect that our future users will comment a lot.
Time and resources for rolling our own solution are not an issue in this stage, but I'm wondering if in the long term this is the best idea, considering the trends.
The way I see it there a few solutions and I'd greatly appreciate it if you could chip in some advice on choosing the best or suggesting an entirely new one:
Rolling our own solution, tied to our member system (until now this
is what we've used, it feels behind the times somehow + it might be hard to keep up
feature-wise in the long run with something dedicated like Disqus)
Our own solution + Login with Facebook, Google,
Yahoo etc (more convenient for users, but I feel that we're losing
the user base)
Using something like Disqus or Facebook comments
(convenient, feature rich and very easy to maintain, but total loss
of control and questionable SEO, even though Google indexes Facebook
comments and recently content generated by JS)
+1 for your conviction that user comments, even (or especially) negative comments, are crucial to your success. Bravo! to you.
Of course, an ideal forum is the one we're using now. There is a process advertised for making an SE-type forum for your site. It depends on generating enough interest right here on SE, but maybe it's worth a shot.
I have wondered for long if a WP-style blog could succeed as a forum-like vehicle if blog comments were not merely enabled but encouraged. Have you thought at all along those lines? I'd like to hear your thoughts if so. To me, Facebook is a giant pita: I hate the sucker. But I'm an FB noob and you've no doubt had more success than I in rasslin' that sumbitch into submission.
Edit: As to getting revisits: you notice that SE does this by "gamifying" the forum: awarding reputation and badges. Good, thoughtful post on the subject at Coding Horror
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.
I'm currently working on a small short-lived project. But despite the size it's complicated enough with very unclear logic. That's why it was started by more experienced developers. They work on it from time to time because it's not their main project.
They made some code drafts with numerous places which 'would be rewritten in the nearest future'. After that they added several another 'temporary pieces'. And then again..
So, now the project is a mess of 'half-working' pieces of code with some hardcoded values, like file names or some constants which 'will be replaced latter with working parts'. The API is awful (nobody thinks about it actually).
And it's really, really hard to do development now (for me it's the main and only project). I caught myself thinking that I spent about an hour every day just to understand again all that tricky 'temporary' things and API weaknesses. And after that hour my brain melts.
I can't just say "guys, your code smells like a trash dump". What's the correct way?
It seems like the ultimate problem is they are writing code and not taking responsibility for its quality.
If this goes against the culture of the organization, it's a matter of making the situation known others. If the developers don't know, and have a modicum of empathy, I would take the "I don't quite understand this. Could you spend a few minutes walking me through it?" with them. They should soon realize what they are doing to you, and good programmers will adjust their practices. This may also have to be done via the management hierarchy-- "In order to progress on project X, I need Y hours of the programmers' time to work with their code effectively." It should either happen or bring up a "Why" conversation that should lead to changes.
If this is the culture of the organization, that's unfortunate. It may mean that the programmers producing the code don't care, and nor do any of the management. This is a bit of a political question-- who is most capable and/or interested in seeing this change? Find allies and proceed best you can. A candid conversation with the developers may be the best choice, as they are the people capable of change and no one else is going to induce them to-- so just ask outright.
Hope this helps.
Push for implementation of a formal code review process. Then they won't dare write code like that in the first place. I recommend using a collaborative tool like SmartBear's Code Collaborator or the free ReviewBoard.
Just like people drive slower when they know the cops are watching, they write better code if they know someone is going to be looking at it.
Are these 'other developers' no longer working on the project? And if so, are you the main person working on it? If the answer to both of these is "yes" the the project is yours. Start to make incremental improvements to make it more readable.
You might also like to show the code to a more experienced developer who didn't work on the project. See if they agree that the code is hard to maintain. Suggest to your boss that you set some time aside to 'finish off' the temporary work and bring it to a point where it is maintainable.
Implementing a formal code review process is also a good idea if you want to prevent this happening again.
And remember it may not have been the other developers fault. Sometimes people are told to spend the minimum amount of time, or are told that the code will be thrown away.
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