The project I'm working on is to re-skin an existing website. The functionality will stay the same, it's just the styles that are changing. In other words, I'm not modifying the HTML, only the CSS files.

The site is pretty complex, with dozens of pages. Logged-in users can have a number of different roles, and depending on their role, the content of the page and what pages they are allowed to see varies.

We're using Git and Github.

I'm trying to write CSS that works as components, so when the same form elements, headings, etc. appear on multiple pages, they are consistent. Most of time this is working well.

Sadly, the format and class names in the HTML are at times messy and unpredictable. When I fix something on one page it can break another. The job is also harder as no one knows exactly all the variations that are possible due to user roles; as such I'm continuously finding new variations as I go along.

I'm making headway by putting a lot of comments in my CSS. If I need to remove a CSS rule, I'll comment it out so that I can still see it with Chrome dev tools, and I'll put a comment in the CSS saying why I removed it and for what page this was done.

This means that if on another page I'm about to add a rule to fix a different problem, there is a better chance that I'll see how it'll break the first page. This allows me to either find a different solution that will work for both pages, or I can make the override page specific.

This has been working quite well for me. If I had free reign and the only goal was to finish the project by the deadline, then this method would be fine. However, my manager is trying to mitigate risk by breaking the work into areas to be completed per sprint. This is counter to how I have been approaching things as something like my typography styles will affect all other pages on the site.

The other issue is that the different stakeholders want to sign off on each section as I go along. The problem is, once I've finished a section it may change if I change CSS that affects it along with the new section I'm working on. I've asked that the stakeholders have a quick unofficial sign off in stages (e.g. per sprint), and have the final official sign off at the end of the project, but this is being met with resistance. I understand why it would be higher risk to do this, but the only way to guarantee that a signed off section will not change is to make ALL future changes page specific.

In addition to this I'm being told that all work that I push to the Git repo should be ready to go live, and as such should not contain any code comments. This is risky for me as I won't know until I've finished the site if I will ever benefit from these comments or not.

Has anyone else been in a similar situation and managed to find a compromise that worked for my development approach and also the desires of management and stakeholders to have a more Agile approach? A more Agile workflow works great when you can break the work into components and know that once something is done it won't be affected by future work. However the nature of this project makes this hard to achieve.

  • 2
    the application would likely benefit of focusing more effort on improving its testability. Communicate a need for this to your management and testers (if your project doesn't have testers, you likely have much much bigger problem than breaking work into smaller chunks). Related (possibly a duplicate): Should we quit trying to do agile if QA takes 12 weeks?
    – gnat
    Jun 5, 2014 at 15:52
  • 1
    "should be ready to go live, and as such should not contain any code comments." - IMHO removing comments is not a sensible approach. git is a source control system, and source code with comments is always preferable over the same without comments. Deployment to production may remove comments (and minify files), but that should be an automated process not something that a human does.
    – miraculixx
    Jun 5, 2014 at 23:19
  • Just commenting to say "I've been there!"
    – Derek
    Jun 6, 2014 at 12:13

2 Answers 2



  1. It looks like testing is not done properly by your team. What your team is expected to do is to have automated testing which ensures that changes to HTML and CSS don't break anything. pdiff would be particularly useful for that.

  2. You consider HTML as "messy and unpredictable". Have you discussed that with your team, and especially the persons who write HTML code? Why would your colleagues make code which you consider being messy and unpredictable? Looks like your team should focus on that.

    Code reviews may help. If it's impossible to do code reviews, try to personally discuss the problems you find in HTML with the colleague who wrote the code (or the part of server-side code which generates this HTML).

    Try also to narrow the problem. Maybe there is just one person in your team who writes "messy and unpredictable" code. Maybe this HTML code is generated by a single component.

    Introducing code standards can also be a solution, depending on your influence on the team.

  3. If you have issues keeping code consistent, why don't you use a CSS preprocessor like LESS or Sass? You can then achieve better code reuse and better consistency.


I'm being told that all work that I push to the Git repo should be ready to go live

Exactly. This is called continuous deployment/delivery/deployment.

  • Continuous integration is when every commit is followed by a build and an execution of automated tests. It helps locating potential regressions.

  • Continuous delivery is continuous integration followed (if tests are successful) by an additional step: the building of a package which can be deployed in production manually.

  • Continuous deployment is continuous delivery where the package is actually deployed automatically.

In all three cases, you're expected to commit code which works. You can't commit for example a bunch of unit tests which currently fail, waiting for the actual code to be implemented, or a piece of code which adds debug info all around the UI.

There are several benefits in this approach.

  • You have a working product at each commit. By comparison, there are projects where the product actually works only twice per year, when it is actually packaged and deployed. This increases the risk of never shipping the product.

  • You (as well as the stakeholders and other concerned persons) have a better visibility on the project.

  • There is less chance to stay at 90% done for months.

If I need to remove a CSS rule, I'll comment it out

  • Instead of commenting code, remove it. Commented code is particularly harmful to the code base, because in six months, nobody knows why is this code here, why was it commented and what to do with it. Comments are intended to clarify the intention of the original author; commented code doesn't have this purpose.

    Don't keep commented code just to be able to rollback to it later. You already use a version control, so reverting to a previous version or looking at what was changed shouldn't be a problem.

  • I don't understand why you're told that production code shouldn't contain comments, and especially why you should remove those comments from your  code. It looks like there is an important step missing in the workflow: the minification. CSS and client-side JavaScript code should be minified automatically, then moved to production. It shouldn't be your task to remove comments from the code you write, and if done manually, it can be a source of human mistakes.

  • 3
    +1 for CSS and client-side JavaScript code should be minified automatically, then moved to production. It shouldn't be your task to remove comments from the code you write, and if done manually, it can be a source of human mistakes. Jun 5, 2014 at 16:10
  • Another thing I'd consider is SASS. You could have easier time componentizing your code with it, even when the HTML you cannot change needs repeated CSS classes, and helps modify them in concert.
    – 9000
    Jun 6, 2014 at 0:28

There is a great book out there called "balancing agility and discipline". It's not so much that the answer is in the book, it is that there is no one right way to do Agile. It's just that the book teaches that each company, each project even, needs to find the best way to do things. In this case, it seems like the HTML is not written such that you can successfully change the CSS and have valid two week sprints. The choices seem to be to change the HTML or change the Agile method.

In all honesty, most of us who write HTML have never really tried to do what you are doing without changing the HTML, so we have no real experience on what is good HTML and what is bad HTML. We can't "smell" something wrong.

The harder question, honestly, is how to change the Agile method to work. It sort of sounds like you have some ideas on the subject, and are just wondering if that is a valid path. I'd say that you should definitely ask for modifications in the Agile methods you are working under to better achieve your goals.

Oh, and you should definitely leave comments in your CSS. The build process should remove them. When the project is finished, you should review them and remove or build upon them for the next person who has to do the same thing, a few years down the road.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.