Debugging the Front End

Solving problems efficiently and productively

Debugging is a process of naming and solving problems. The most time consuming part is identifying the problem.

The front end uses these tools to debug:

Web Developer

Web Developer helps us locate the problem.

screenshot of web developer plugin targeting a page element

Google

Google helps us describe the problem.

  1. Identify key words.

  2. Reformulate the query.

  3. Discount red herrings with boolean operators.

Your Brain

Your brain helps us to evaluate Google's solutions.

Evaluating Sources

Google has many answers, but they're not all useful, accurate, or informed. So how do you know what advice to take and what advice to reject? How can you make well-advised coding choices?

Some Authoritative Sources

Not all these sources will agree with each other, and they won't always give appropriate solutions, but they will generally provide evidence and a logical chain of reasoning that you can follow so you know why you're doing something.

Sources which do not provide both evidence and a chain of reasoning are not valuable because you cannot accurately test, reproduce, or adapt their methods.

So far:

Web Developer
What
Google
How
Your Brain
Why

If you do not know why you are doing something, you are programming by coincidence, and your contribution may be difficult to maintain and ultimately worthless.

Conclusion

Notes on best practice

Over time, you will build up a kind of horse sense and your debugging process will speed up. A number of layout problems re-present in development as new structures are added and the cascade is refined.

You will begin to reflexively validate XHTML, as many many layout bugs are caused by bad nests and poorly formed structures. You will acquire quirks-sense: Internet Explorers 4-7, for example, have an enormous number of bugs caused by unintentional triggering of its hasLayout property, and you will find yourself often reformulating your query to include +hasLayout.

It is important, however, to uphold the analytical method, as it is just as mistaken to rely on magic spells when you know a hundred as when you only know three. If you don't record or explain your process, the project cannot collectively gain from your insight. Debugging is therefore constructive in two ways: it solves problems we have and it helps us build a store of tools to solve problems we haven't yet encountered.

Pragmatism, Perspective

Sometimes reported code issues are mistaken in their priorities. Sometimes the coding labour and kilobytes required to resolve an issue are not worth the solution. Sometimes the changes needed are disproportionate to the reported issue. It is more important, for example, that the Archive be accessible to screenreaders, than that every link have the exact pixel padding for every visual browser. Before you commit, you must always ask yourself: is this response proportionate? Is it necessary? Is it productive? Every decision you make has both costs and benefits. Name the cost of your decision.

It is not necessary or desirable for the Archive to look identical in every browser. "Pixel precison" is not a reasonable or desirable goal because our layout is designed to be flexible and adaptable, so it will work in contexts not yet conceived. When adding styles, you must consider that keeping the code simple and easy to maintain is a priority. Part of working on Front End is constantly explaining this to the rest of the AO3 staff. It's a social hack. It can be frustrating, but it is a necessary part of upholding our principles of accessibility and flexibility resting on a strong base of typographic, relational design.

I don't have great advice for you in this; I have never succeeded in this advocacy. Some resources you might find useful are: The Web is Not Print, Web Design is Not Print Design, You can't Get Every Page To Look Identical So Stop Trying, accessibility of fixed, liquid, and elastic design, Photoshop Layout is NOT Your Friend...there are copious resources online. Essentially you have to prepare yourself for the fact that the rest of AO3 will think you are incompetent, unreasonable, and kinda angry! But it's okay, it's worth it.

More complex and specific methods

The approach laid out is a set of general principles for you to build upon. Listed following are some more detailed and specifical methods you can use:

← Back