Community
Participate
Working Groups
Build ID: M20070921-1145 Most code in the CDT lacks Javadoc comments, or any kind of helpful comments at all. This is in sharp contrast with other Eclipse projects I've seen, where public APIs are usually well documented. Lack of comments is a very high barrier for anyone who wants to contribute to CDT or integrate with it.
100% agree... But, I think this bug will be completely ignored.
Yeah, it would be hard to judge when it's fixed. When more than half of the CDT is less than totally undocumented? I think half the classes have at least one comment so this may already be fixed. Please advise. BTW, jokes aside, this is a well known issue and we are actively looking for solutions. None are easy, though.
(In reply to comment #2) > BTW, jokes aside, this is a well known issue and we are actively looking for > solutions. None are easy, though. On the surface the solution seems pretty darn simple: everyone just start writing comments! ... But the difficult problem isn't the lack of comments, its a lack of motivation to write them. This is a difficult problem. In a community of non-documentation-writers a sole documentation-writer will be at a disadvantage. Time spent documenting is time taken away from coding. The documentation-writer would be making a sacrifice while the other committers would get more work done. The problem here is the definition of "work done". Currently in CDT land "work done" is defined as having some working code with a few JUnits. We need to redefine "work done" so that it includes high quality API and source level comments, and additional design docs or wiki docs for larger features/components. (I also think we should be doing more code review.) How do we enforce this? I'm not entirely sure it can be strictly enforced. The word "community" gets thrown around a lot, so instead of enforcement writing docs needs to be part of the culture of the community. It should be something we all do just because its the right thing to do. Like saying please and thank you is the accepted thing to do in polite society. Maybe that's the motivation we need, a general acceptance of certain community values. For example, there is no law enforcing politeness, but if you act rude then you will be frowned upon and won't get invited to parties. Similarly writing docs should be the "polite" thing to do, and if you don't do it you risk losing the approval and respect of your peers. Unfortunately right now writing documentation is not a shared value in the CDT community.
> Yeah, it would be hard to judge when it's fixed. When more than half of > the CDT is less than totally undocumented? I think half the classes have > at least one comment so this may already be fixed. Please advise. > > BTW, jokes aside, this is a well known issue and we are actively looking > for solutions. None are easy, though. The comments I miss most are the class-level comments of interface classes (ISomething) and very central manager classes like ManagedBuildManager and CoreModel -- that would already be an immense help for all new to CDT. If I know what a class is for, and what relationship it has to other classes (like, IManagedBuildInfo --> "managed by ManagedBuildManager, holds configurations, and is live data structure loaded/saved via ICProjectDescriptions"), then figuring out methods is already much-much easier. So if there's **really** a willingness to improve, that's what I'd suggest to start with: class-level comments for all ISomething classes and a handful of other, very central classes. I can try and help, but it would be better if original authors or current maintainers of classes would take some minutes/hours of their times to do it. Despite having studied parts of CDT and writing up dome of my experiences at http://cdt-devel-faq.wikidot.com, I don't feel I'm qualified enough. Well, for a start I could try putting down what I currently know, if CDT team members are willing to revise and expand it. I also think that documenting the code would have benefits for the developers too: 1) less traffic of stupid questions in [cdt-dev]. If it's documented, it won't be asked (or and replies can be shorter, possibly just RTFC) 2) help fellow developers build upon my code, and with less misunderstandings. Like, who the hell knows what ICSettingEntry.RESOLVED means, and whether I need to set it if I create a CSettingEntry on my own??? I need to spend half a day hunting for occurrences in the source code, in order to deduct what it can be possibly used for; and in the end there's still a good chance that I misunderstood something. And maybe then my code will mislead other developers too, and so the plague spreads.... 3) this may sound strong, but on the long term, it may just be vital to the survival of the CDT code. There are already multiple generations (2.x, 3.x, 4.x) of data structures intertwined, with heaps of code doing mapping between them, possibly involving "tweaks" (think IConfiguration and ICConfigurationDescription, and all the code to keep the two consistent), lots of utility and "manager" classes, etc. Do REALLY all CDT team members know 100% what class is for what, what's the old/deprecated way and what's new/preferred, how to keep things consistent, etc.....? Documenting things would help staying on top.
Today's post on cdt-dev: | Subject: [cdt-dev] Need info on CPPUnknownClass | | Hi Andrew, Bryan and Doug, | For understanding issues related to bug 214017 I need background information | on ICPPInternalUnknown, CPPUnknownClass, CPPUnknownScope and few related | classes. | 1. What do CPPUnknownClass and CPPUnknownScope classes represent? What is | the basic idea behind them? What purpose do they serve? | 2. Why are there no PDOM equivalents? Should they be added? | 3. Why does CPPTemplateTypeParameter implement ICPPInternalUnknown, but | PDOMCPPTemplateTypeParameter does not? | 4. Why doesn't CPPTemplateTemplateParameter have a PDOM equivalent? Should | it be added? | Any insight will be highly appreciated. | | -sergey As if he was posting it exactly to support my points... 1. so it indeed *does* happen that CDT developers themselves are not sure what purpose some class serves -- docu would benefit them too 2. what he misses (esp. in bullet 1) is exactly what should have been written down in the class-level doc of those classes in the first place. This seems to confirm that documenting should begin with class-comments of interface classes and a few central classes Now he cannot continue for a few days, until he actively gathers all information he needs. This delay and wasted effort could have been spared (but at least reduced) by the author of those classes spending 10 minutes on writing a useful class comment.
(In reply to comment #4) > So if there's **really** a willingness to improve... See, thats the thing, I don't believe there is a willingness to improve. We get comments all the time that are related to lack of docs and the policy hasn't changed. Some of the newer APIs in CDT are commented, like the IIndex API. But the vast majority of the code is undocumented. > 1. so it indeed *does* happen that CDT developers themselves are not sure > what purpose some class serves -- docu would benefit them too Absolutely, this happens all the time. Also, having docs makes it much easier and faster for new contributors to get up to speed. When I first started on CDT it took me a long time to get even a bit comfortable with the core. > This delay and wasted effort could have been spared (but > at least reduced) by the author of those classes spending 10 minutes on > writing a useful class comment. I agree, sure you can save ten minutes by not commenting your code, but you are causing several other developers to waste more then ten minutes each trying to understand the code. Documentation can be thought of as an investment in overall team productivity. > 3) this may sound strong, but on the long term, it may just be vital to the > survival of the CDT code. > Do REALLY all CDT team members > know 100% what class is for what, what's the old/deprecated way and > what's new/preferred, how to keep things consistent, etc.....? In my opinion this is a major issue. There are a couple very active commiters on the CDT core and I wonder what would happen if any one of them decided to quit working on CDT. Certain individuals have a lot of intimate knowledge of CDT internals, but that knowledge hasn't been written down. If a key individual left it would create a major stall in development. The developers that would take over would have nothing but a huge heap of undocumented code to deal with.
There is a willingness to improve and as I mentioned we are actively looking for solutions. As with all projects, the CDT is strapped for resources and we appreciate all help in cleaning this up. But whatever you do, please don't interpret the lack of progess on willingness.
(In reply to comment #5) > Today's post on cdt-dev: > | Subject: [cdt-dev] Need info on CPPUnknownClass > | > | Hi Andrew, Bryan and Doug, > | For understanding issues related to bug 214017 I need background information > | on ICPPInternalUnknown, CPPUnknownClass, CPPUnknownScope and few related > | classes. > | 1. What do CPPUnknownClass and CPPUnknownScope classes represent? What is > | the basic idea behind them? What purpose do they serve? > | 2. Why are there no PDOM equivalents? Should they be added? > | 3. Why does CPPTemplateTypeParameter implement ICPPInternalUnknown, but > | PDOMCPPTemplateTypeParameter does not? > | 4. Why doesn't CPPTemplateTemplateParameter have a PDOM equivalent? Should > | it be added? > | Any insight will be highly appreciated. > | > | -sergey > > As if he was posting it exactly to support my points... > 1. so it indeed *does* happen that CDT developers themselves are not sure > what purpose some class serves -- docu would benefit them too > 2. what he misses (esp. in bullet 1) is exactly what should have been written > down in the class-level doc of those classes in the first place. This > seems to confirm that documenting should begin with class-comments of > interface classes and a few central classes > Now he cannot continue for a few days, until he actively gathers all > information he needs. This delay and wasted effort could have been spared (but > at least reduced) by the author of those classes spending 10 minutes on writing > a useful class comment. You do need to understand the history and structure of the CDT. We are all CDT developers. The fact that you are looking at the code makes you a CDT developer too. As you learn about the code you are reading, and given your enthusiasm for the issue, I should be able to expect patches with new documentation from you, no? Second, the code Sergey is talking about was written in haste to meet deadlines by developers that no longer work on the CDT. It would be a hell of a lot easier if we didn't have turnover or fixed deadlines, but that is the fact of life that we have to endure on the CDT and what makes solutions even more difficult.
(In reply to comment #7) > There is a willingness to improve and as I mentioned we are actively looking > for solutions. As with all projects, the CDT is strapped for resources and we > appreciate all help in cleaning this up. But whatever you do, please don't > interpret the lack of progess on willingness. If there really was willingness then there wouldn't even be a problem. In fact the real problem here is exactly the lack of willingness, the lack of motivation. How are we actively looking for solutions? What potential solutions have been considered? > As you learn about the code you are reading, and given your enthusiasm for > the issue, I should be able to expect patches with new documentation from you, > no? I have done exactly this in the past. I wrote up a wiki page describing how the DOM parsers work, then I posted a link to the dev list. That dev list post got zero replies. Not one correction to the docs, not one single reply saying "thanks for writing documentation". So you can see why I personally believe that the documentation issue is being ignored. And wouldn't it make much more sense for the author of the code to write the docs, especially when its fresh in his mind. > It would be a hell of a lot > easier if we didn't have turnover or fixed deadlines, but that is the fact of > life that we have to endure on the CDT and what makes solutions even more > difficult. This is a very weak argument. This is like saying that you can't jog a mile because the earth's atmosphere doesn't contain enough oxygen. Deadlines are an environmental constant, they will always be there, they are not unique to CDT, and they are not an excuse. Furthermore, as I have pointed out, documentation has the potential to *increase* productivity. And turnover becomes less of an issue if you have docs because new developers can get up to speed quicker. It seems to me that docs would actually help improve the issues you mention here. And really, how long does it take to put in a simple "this is what this class is for" description.
(In reply to comment #9) > (In reply to comment #7) > > There is a willingness to improve and as I mentioned we are actively looking > > for solutions. As with all projects, the CDT is strapped for resources and we > > appreciate all help in cleaning this up. But whatever you do, please don't > > interpret the lack of progess on willingness. > If there really was willingness then there wouldn't even be a problem. In fact > the real problem here is exactly the lack of willingness, the lack of > motivation. Well, Mike, it sounds like you're motivated. I look forward to any solutions you come up and your efforts to achieve buy-in from the CDT community. I will certainly support you on this. In the meantime, I intend to follow through with the committment I made at the CDT Summit to get the ISV docs going in CDT 5.0.
Doug, Nobody's in a better situation to actually do something than you. You are the CDT Project Lead. If you publicly say documentation is important, people will listen. If you say, that, for example, by CDT 5.0 you'd like to see all public interface classes to be documented on class level, it may actually happen. For the next milestone, you may ask X to document interface classes in package org.eclipse.cdt.blah (class level comments only), ask Y to document classes in package org.eclipse.cdt.blahblah, and so on. That's maybe 2-3 hours of their time? Won't kill them. They've all wasted much more time in the past, on figuring out undocumented classes written by someone else. It's all on you. If you need to be convinced that it's worth it, re-read previous comments. If you don't act, that will be also a testament of something. > And really, how long does it take to put in a simple "this is what this class > is for" description. Exactly.
(In reply to comment #11) > Doug, > Nobody's in a better situation to actually do something than you. > You are the CDT Project Lead. If you publicly say documentation is important, > people will listen. > If you say, that, for example, by CDT 5.0 you'd like to see all public > interface classes to be documented on class level, it may actually happen. For > the next milestone, you may ask X to document interface classes in package > org.eclipse.cdt.blah (class level comments only), ask Y to document classes in > package org.eclipse.cdt.blahblah, and so on. That's maybe 2-3 hours of their > time? Won't kill them. They've all wasted much more time in the past, on > figuring out undocumented classes written by someone else. > It's all on you. If you need to be convinced that it's worth it, re-read > previous comments. > If you don't act, that will be also a testament of something. > > And really, how long does it take to put in a simple "this is what this class > > is for" description. > Exactly. I have and that is what I'm referring to with the ISV docs I've committed to get going. We did have a good discussion on this at the CDT Summit. The committers are aware of it. But it will take time to get together, especially given that I'm trying to get up to speed on my new job.
Doug, Writing CDT documentation for ISVs is very welcome and going to be very useful. However, it sounds like standalone docs -- how is that going to solve the problem of missing source code comments? What are you as Project Lead going to do about missing source code comments? Encouragement? Policy? Goals? Deadlines?
(In reply to comment #13) > Doug, > Writing CDT documentation for ISVs is very welcome and going to be > very useful. However, it sounds like standalone docs -- how is that > going to solve the problem of missing source code comments? Well, much of the ISV docs will be generated from Javadoc, we'll at least get comments for the APIs. > What are you as Project Lead going to do about missing source code comments? > Encouragement? Policy? Goals? Deadlines? I've already encouraged. The CDT committers are all professional developers. They already know the value of code documentation. And to be honest, the code you are complaining about was written by people no longer contributing to the project, so there's not much I can do there. And to be further honest, we really do have bigger issues than the shortage of code comments that need my attention in the short term. That is why I am looking for help from the community to drive this issue.
(In reply to comment #14) > The CDT committers are all professional developers. > They already know the value of code documentation. Clearly some don't because if they did they would be writing it. If this were true we wouldn't be having this discussion (or flame war, I'm not sure anymore). > And to be further honest, we really do have bigger issues than the shortage of > code comments that need my attention in the short term. This is probably true for existing code that isn't commented. Many of us don't have time to go back and dig through old code at this point in the cycle. But after the 5.0 release would be a perfect time to take a breath, relax, then go on a refactoring and documentation frenzy over the summer. This is an example of a potential solution that we should be discussing here instead of arguing back and forth. New code thats being written right now is different. Everyone should be commenting their code as they go, starting right now. I find its really not an issue at all to write comments as I code. Sometimes I'll be in the middle of describing my solution and I'll realize that I forgot a corner case. Writing docs as you go forces you to think twice about your solutions, and that leads to better code. And frankly it seems to me that you just want this issue to go away. Thats not going to work, we need to do something. We need to work together, arguing is not helping. > And to be honest, the code > you are complaining about was written by people no longer contributing to the > project, so there's not much I can do there. We should still try to go back and do something at some point. In fact its the older code thats the worst offending in many respects. Again, I suggest a major refactoring pass when the heat is off. Taking a break from writing new features and just focusing on improving existing code for a bit would help greatly. (In fact I think cleaning up the code itself is even more important than comments.) > That is why I am looking for help from the community to drive this issue. Right, the community is the key here. Doug, if you really want me to take the lead on this I will. But frankly I don't think I have enough clout in the CDT community to make much of a difference. But if you say you will back me up then I'll try. All I can think of right now is to to create a discussion on the cdt-dev list, get the community to work together to come up with a set of official CDT best practices, and perhaps take a vote on it. I guess it would be unofficial but if we actually followed it that would be a big win for CDT.
Well its been a week since I posted what I thought was a real potential solution, and there has been no replies. Screw it, I'm not going out on a limb for this. I would need backup from you Doug anyway, and your lack of reply means I can't count on you for that, even though you said you would support me, I just don't believe it. Besides, new documentation policies are not my job, its your job as project lead. And if you don't see the problem here, then so be it. CDT will remain mostly undocumented, and that will be the official policy. Case closed. I will continue to fully comment my own code, but I'm not wasting any more of my time discussing this issue. Closing this bug as WONTFIX.
Reopening because the problem still exists, and it is a real problem.
