21
\$\begingroup\$

What do you believe are the Guiding Principles of Code Review? What are the purpose and mission of the site?

Recently (and not so recently) a lot of effort and hair-pulling has gone into discussing whether some questions or concepts are in-scope, on-topic, or useful on Code Review.

Are there key "foundations", or "Principles of Code Review" that have to be satisfied in all circumstances when discussing site scope, and on-topicness?

\$\endgroup\$
16
\$\begingroup\$

(Taking off my moderator hat....)

If I could sum up in 1 sentence what I believe are the most central concepts in Code Review, it is:

Code Review is a site where you can present your best programming efforts in an ego-sensitive environment in order to receive constructive and honest criticisms designed to help you be a better programmer.

I want to express this in a slightly different way too:

Code review is not about getting people to the next step in their project, Code Review is about getting people to think differently.


Details

I have tried to be very careful with my wording above, but I want to elaborate on a few things... and breaking that first sentence down in to 4 statements seems useful:

Code Review is a site where:

  1. you can present your best programming efforts
  2. in an ego-sensitive environment
  3. in order to receive constructive and honest criticisms
  4. designed to help you be a better programmer.

Best Programming Efforts

If you ask a question and the code it contains does not please you, does not make you proud, or you don't feel has made the best of a challenging situation, then the code is not ready for Code Review. You have not submitted your best efforts. You don't need someone else to tell you it's not good code if you already know it is not the best code you can do. You are not going to learn as much as you could if you already know how to take things to the next level.

Asking people to tell you what you already know is a waste of your time, and theirs, and in some ways is disrespectful and inconsiderate. Thinking "harder" is not the same as thinking "differently".

Submit your best, and obtain the best value.

Ego-sensitive environment

Code Review is unlike most (all?) other Stack Exchange sites - by definition we ask people to offer up their most prized creations for criticism. This makes question askers vulnerable, and we need to be sensitive to this. If we tease, ridicule, or otherwise demean people who make themselves vulnerable, we will quickly fail. We have to understand and be sensitive to the fact that we are dealing with peoples' creations, their "babies". Respect that. It is a courageous thing to do. Question askers will be sensitive and defensive, but, most importantly, they will be receptive.

When people put their ego aside, and come looking for ways to extend themselves, that is a rare opportunity to make a difference in someone's life. Make a positive difference. Help them think "differently".

Constructive and Honest Criticisms

The goal of Code Review is to be helpful, not hurtful. Human perception is very sensitive to insincerity, spite and malice. Anything other than sincere, honest criticism will be quickly dismissed, will add no value, and will undermine the values of this site. Somehow, and I am no psychologist, but somehow, people are able to differentiate between sincere, wrong criticisms, and insincere right criticisms. I have no problem with people giving bad or inappropriate criticisms if the intent was honest (sure, I won't upvote it, but...). On the other hand, anything less than an honest and sincere review (with good advice, or bad) will remove value from the site as a whole.

People will not "think differently" if they do not trust the sincerity of the source.

Designed to help you be a better programmer

This is what the site is about... helping people be better at what they do. Extending, enlightening, enhancing them. Planting a seed of a different mindset. Exposing them to a different perspective. Taking them somewhere they had not considered.

The immediate target of the help is the person asking the question, but often it is possible to read other people's questions, and the answers to them, and to learn something new there too. The value is that we can identify (empathise) with the asker, and learn by proxy.

If you can show them something new, in a way that is a step up from where they are, then the next time they will think "differently". You will have won!


Assumptions and Constraints

Code Review is not an isolated concern. It exists in the ecosystem of the whole of Stack Exchange. This imposes some constraints, and establishes some assumptions:

  1. Code must be working - even though we often could help people with broken code, it is not in scope here because Stack Overflow is the place for specific programming questions. More specifically, debugging people's code for them is not helping them to be a better programmer. It is just doing their work for them. If people need help with the process of debugging their code, then Stack Overflow (and Google) is a good place to ask for help in identifying what debugging tools are available and understanding how they work.

  2. Understanding code - helping people to understand the code they have is not on topic because the code already exceeds their abilities. There is no way to guide a person in to a new way of thinking when that new way of thinking is already defined in their question. That requires two steps, first, guiding them to the way of thinking in their question, then additionally guiding them to the way of thinking you want to contribute. Only 1 question per question is a rule (or it should be). This situation also violates the "best programming efforts" concept.

  3. Golfed or golfing code - helping people to golf their code is not doing a code review, it is playing a game with them. It is a collaboration in an attempt to satisfy a competitive objective. While golfing code may be fun, and entertaining, it is not something that is on-topic here. As it happens, there is Programming Puzzles & Code Golf which is designed to be a place where this is on topic, but, even without that site, the concept is off-topic here because we are a question and answer site, not a collaboration-to-compete cooperative. We have no competition, no losers - everyone wins!


Summary

Code Review is a site where you can present your best programming efforts in an ego-sensitive environment in order to receive constructive and honest criticisms designed to help you be a better programmer.

Personal

I get good value from questions I ask if I put my best effort in to them, because then every suggestion is something new.

When I answer questions I try to reveal a different way of thinking so that the question asker (and subsequent readers) are enriched. That different way of thinking only has to be new to the question asker, not to the world in general.

\$\endgroup\$
  • 13
    \$\begingroup\$ Beautiful answer and read, but I'll be honest. This part concerns me a little. If you ask a question and the code it contains does not please you, does not make you proud, or you don't feel has made the best of a challenging situation, then the code is not ready for Code Review. People often come here because their intuition tells them that a piece of code smells, but they don't have the experience to know how to remove the smell. (Including me.) I'm not saying it shouldn't be your best code. It should be your best code. But you might not be proud of your best code. \$\endgroup\$ – RubberDuck Mar 26 '15 at 9:31
  • \$\begingroup\$ "1 question per question" is not a clear rule, as some questions lists three questions. \$\endgroup\$ – Simon Forsberg Mar 26 '15 at 11:46
  • \$\begingroup\$ @SimonAndréForsberg clearly we need to educate them (and I guess sometimes myself, when I do post questions on CR) on the "Single Question Principle". :p (I kid) \$\endgroup\$ – h.j.k. Mar 27 '15 at 10:34
  • 2
    \$\begingroup\$ I think it is important to clear up that what I have done is just rambled about the ideals and goals (as I personally see them) of code review as a site. I am fully aware that the reality is a lot more messy. I am not trying to use the ramblings as a "meter" against which questions are closed, or voted on. Rather, it is a way for me to assess whether site policy discussions are aligned with the goals and values of the site, or whether the topics being discussed would hinder or devalue the site \$\endgroup\$ – rolfl Mar 27 '15 at 10:38

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .