Style checking and linting are closely related concepts that differ primarily in that:
- Style rules are aimed at reducing the cognitive load (see also) imposed on engineers attempting to understand or work with your codebase.
- Linting is aimed at preventing bugs enforcing a ban on specific patterns and practices that are both considered harmful and detectable in an automated manner.
We consider these together because often style rules and linting bleeds together. For example, is it a stylistic concern that all
A common rule among style checkers is the prevention of magic number use. Let's take a look at an example where preventing use of magic numbers might save our bacon. Say we implement this block of code somewhere in our application:
There are three primary places one can implement these checks - at compile time, at commit time, or as part of the PR merge process. As with most automation, running it earlier is generally better - at least at compile time the developer is likely still in the context of the offending code. Sometimes this isn't possible - maybe your code doesn't even have a compile step, or maybe your linter is really heavy and including it in your compile step would cause an unacceptable delay for the developer. If you have a good reason, later is OK too, it just has to be balanced against the increased cost of getting back into context to fix whatever problems are uncovered.
The other part of the 'how' is your internal education process about these kinds of rules, and process for updating / adding / removing them. All developers have to be invested in the process for it to matter (and for them to not try to work around it), so it's worth your time to demonstrate real benefits in your project and make sure everyone is on board. Another consideration is that you should do this as early as possible, the most common failure of attempts to implement rules like this is that they are made on large extant codebases that have thousands or more violations. Ain't nobody going back through and fixing all that.
For Scala my favorite is ScalaStyle - it's mostly style rules but also has some good functional rules.
if statements have braces, or is not including them a harmful practice because it frequently leads to bugs where logic accidentally escapes control flow? Hard to say, so we just roll them into one topic.A common rule among style checkers is the prevention of magic number use. Let's take a look at an example where preventing use of magic numbers might save our bacon. Say we implement this block of code somewhere in our application:
def hasFlag(bits: Int, flag: Int) = {
((bits >> flag) & 1) != 0
}
def doSomeLogic(userPreferences: Int) {
// bit 0 is make profile public
if (hasFlag(userPreferences, 0)) {
// show public profile
}
// bit 1 is receive site emails
if (hasFlag(userPreferences, 1)) {
// send daily digest email
}
}
// sets the bit at $flag position to $enabled
def setFlag(bits: Int, flag: Int, enabled: Boolean) = {
val value = if (enabled) 1 else 0
bits | (value << flag)
}
def storeUserPreferences(receiveEmails: Boolean, publicProfile: Boolean) {
var userPreferences = 0
userPreferences = setFlag(userPreferences, 0, receiveEmails)
userPreferences = setFlag(userPreferences, 1, publicProfile)
// store userPreferences...
}
object UserPreferenceBits extends Enumeration {
type UserPreferenceBit = Value
val ReceiveEmails = Value(0)
val PublicProfile = Value(1)
}
// checks whether an integer has the bit at $flag position enabled
def hasFlag(bits: Int, flag: UserPreferenceBit) = {
((bits >> flag.id) & 1) != 0
}
// sets the bit at $flag position enabled
def setFlag(bits: Int, flag: UserPreferenceBit, enabled: Boolean) = {
val value = if (enabled) 1 else 0
bits | (value << flag.id)
}
def doSomeLogic(userPreferences: Int) {
val publicProfileFlag = 0 // BAD!
val receiveEmailFlag = 1 // BAD!
// bit 0 is make profile public
if (hasFlag(userPreferences, publicProfileFlag)) {
// show public profile
}
// bit 1 is receive site emails
if (hasFlag(userPreferences, receiveEmailFlag)) {
// send daily digest email
}
}
def storeUserPreferences(receiveEmails: Boolean, publicProfile: Boolean) = {
var userPreferences = 0
val receiveEmailFlag = 0 // BAD!
val publicProfileFlag = 1 // BAD!
userPreferences = setFlag(userPreferences, receiveEmailFlag, receiveEmails)
userPreferences = setFlag(userPreferences, publicProfileFlag, publicProfile)
// store userPreferences....
userPreferences
}
Where and how to deploy style checking & linting
There are three primary places one can implement these checks - at compile time, at commit time, or as part of the PR merge process. As with most automation, running it earlier is generally better - at least at compile time the developer is likely still in the context of the offending code. Sometimes this isn't possible - maybe your code doesn't even have a compile step, or maybe your linter is really heavy and including it in your compile step would cause an unacceptable delay for the developer. If you have a good reason, later is OK too, it just has to be balanced against the increased cost of getting back into context to fix whatever problems are uncovered.
The other part of the 'how' is your internal education process about these kinds of rules, and process for updating / adding / removing them. All developers have to be invested in the process for it to matter (and for them to not try to work around it), so it's worth your time to demonstrate real benefits in your project and make sure everyone is on board. Another consideration is that you should do this as early as possible, the most common failure of attempts to implement rules like this is that they are made on large extant codebases that have thousands or more violations. Ain't nobody going back through and fixing all that.
For Scala my favorite is ScalaStyle - it's mostly style rules but also has some good functional rules.
