I work for a small software development house (10~ developers, a few product managers and a few support staff) that sells various products and services to organisations internationally through resellers. I arrived in the job 7 months ago into a role opened up by a developer who left after 3 years. The company has maybe been around for 10 years. Basically they have about 30+ separate products (in 30 separate .NET solutions which may consist of 10+ projects within each of those solutions). I would estimate each project or solution to be of medium to large size.In each project there is absolutely no source code comments at all. There's also no architecture diagrams or documentation for how the application is designed or the code hangs together. There's some business analysis (use case) type documentation for how the program is supposed to work, when it was first created, but that's it.As a new person to the company, for the past 7 months I've been thrown into various projects and had to fix bugs in these various products. I have an IT degree and I'm perhaps intermediate-senior level in HTML5/PHP/web development, also junior-intermediate level in .NET development. They recruited me for my web development skills and wanted to progress my .NET skills. I accepted as it was paying more than my old job in PHP and thought it would be useful for my career and more job options to have some more .NET development background.However each day I feel as though I'm floundering in the deep end and treading water. For starters to get anything done, reading the code is mostly pointless as you've got no baseline from where to start or find or fix a bug in this new project you've just been assigned. I end up talking to one of the other senior programmers to get an idea of where to start. By senior, I mean they've been there for 4 years and have a general idea of how a particular program might work. Even they didn't even write most of the software, a lot of it was written by a few older guys that have since retired and left the company.The code itself is very complex in my opinion. Maybe it's just because I'm not that skilled in .NET but there seems to be lots of unnecessary layers of complexity. You might have your basic 3 layers for MVC. Then whoever wrote the application added in more layers of code for the project, maybe to structure the application. For example, the front controller calls a few classes which bootstraps the application, then that calls the controller, then a method there might call a model then that model calls a business layer, then that calls a business logic layer, then that calls a data layer, then the data layer calls a service which has more classes to call stored procedures and get the data from the database. This is a far cry from my experience in PHP which even in complex web apps would still be as simple as the front controller calling a controller which calls the model, the model retrieves data from the database and renders it to the view/webpage. I mean what benefit are all these extra layers adding?Another thing, there might be a class, then they create an interface for just that class. There's no other classes using that interface or inheriting from it. They just create an interface for every class pretty much. As far as I can see there's no unit tests using the interfaces either. I'm sure it must've made sense to the senior developer writing it, but the meaning is lost on me.The other thing they like to do is because they don't have many developers in house, they write up some specs/documentation for a system they want, then outsource the project to another company to develop. Then once it's finished they bring it back in house for the local developers to maintain it. One company they outsourced it to was a local development services company, but that company in turn outsourced the development efforts to some developing country. Now I'm back here maintaining their code base, and it doesn't have any comments either. The program itself is probably the size of say Photoshop as an example. There's literally multiple layers of complexity and large parts of the code are commented out in chunks. Why is it commented out? Do they think they'll use that code in the future? No idea. No-one else knows either. The people that worked on it in the outsourced company have since left that company and disappeared.Early on when I joined the company, I was reading some convoluted project code and added some comments into the code so I could make sense of it later on if I had to come back to the project. A few days later one of the more senior developers there came and asked me some questions about that project. I found the thing he was trying to figure out was actually the thing I had figured out the other day. I had written a comment in the code explaining what it did and I showed him. Then he immediately deleted the comment without reading it, scrolled up the code and asked me another question. Then I said, well that can be explained in the comment below which you just deleted. He goes back and undoes the deletion then reads the comment... then he finally understands.I asked him why none of the code has any comments and his rationale was that the comments get outdated and become pointless. Well yeah, comments are supposed to be maintained along with the code. You update the code, you update the comment at the same time. The development manager's rationale for no comments was that good code should be understandable without comments.OK so they've got these hugely complicated systems and the only people that have some idea of how they work are the people that were there in the beginning or who have been working on them for many years. Basically if these people leave it would practically ruin the company in my opinion because no newcomers coming along will understand the code base and be able to maintain it.When I get asked to do something there, like add a new feature into the system, I think I could probably knock it out in HTML5/jQuery/PHP in a few days no problem. In this company, I've got to first figure out the system, then understand how the code works with no comments, then figure out where to put my code, then code it. Days turn to weeks. It's like searching for a needle in a haystack.My philosophy is to design and code something well the first time, in the simplest way possible to get the job done, while making the code easily maintainable and understandable so if a new person had to pick it up they can just run with it straight away. But that seems very contrary to what this company does.So my questions:Is not commenting code a common practice in the software industry?Why is there so much aversion to commenting code?How can I perform my job well in this environment?Should I recommend they start commenting their code or leave them to it?
Working in a company that does not comment their code at all?
programming practices;maintenance;comments
There are a lot of reasons for no comments, but I think it usually boils down to incompetence, poor communication skills, and/or amateurism.Is not commenting code a common practice in the software industry?Only the bad areas of the industry; bad code rarely has enough comments, just as good code rarely has too many. Why is there so much aversion to commenting code?There's not. If anything, there seems to be more and more tools to support better, more effective commenting. This may sound sinister, but I've known a few bad developers that leave comments out for job security - they don't want other people understanding their code. Fortunately, the best developers think this is fickle and refrain.How can I perform my job well in this environment?  Should I recommend they start commenting their code or leave them to it?I think the bigger question is, does it matter? Let's say that you somehow do a great job and everyone's writing comments. Great, now what? Well then you're at the starting line and can finally start improving the code for your customers now that everyone understands the code; if you had such a hard time with something as easy as comments, is it likely you'll find success here?Personally, I've found that the level of confusion one experiences on a project is a pretty accurate measure of competence - inversely proportional of course. I think as a developer trying to grow, it would be easy to think the confusion is due to your own incompetence, but think about this: would a strong team hire someone and then let them drown in an ocean of confusion? No! They'll empower the new guy so he can return the favor.I've experienced similar situations first- and secondhand. Typically, the developer is either in over their head or in a tar pit. I think the response to you asking them about the lack of comments is most telling in this case:... the comments get outdated and become pointless.No, because refactoring comments and documentation is part of refactoring code! You're spot on.... good code should be understandable without comments.Mostly true, but then why did we just have this dialog?