التعليقات والأسلوب وقابلية القراءة

التعليقات أحادية السطر باستخدام #

# This is a comment — R ignores it completely
x <- 42   # inline comment after code

# Bad comment (states the obvious):
y <- y + 1   # add 1 to y

# Good comment (explains intent):
y <- y + 1   # shift index to 1-based for output display

cat('x =', x)

عناوين الأقسام باستخدام ------

# Data Loading -------------------------------------------------------

# This section loads raw CSV files from the data/ folder

# Data Cleaning =======================================================

# Remove duplicates and fix missing values

# Modeling ############################################################

# Fit linear model and evaluate

cat('Section headers improve navigation')

اصطلاح التسمية snake_case

# Good: snake_case
user_age <- 25
monthly_revenue <- 15000
calculate_mean <- function(x) mean(x)

# Avoid: dots in names (looks like OOP method calls)
user.age <- 25       # confusing

# Avoid: camelCase (inconsistent with tidyverse)
userAge <- 25

# Avoid: ALL_CAPS (reserved for true constants by convention)
MAX_RETRIES <- 3     # acceptable for config constants only

cat('snake_case wins')

المسافات حول العوامل

# Good: spaces around <- and operators
x <- 10
y <- x + 5
result <- x * y - 2
is_valid <- x > 0 & y < 100

# Bad: cramped
x<-10
y<-x+5

# Function arguments: = without extra spaces is fine
mean(x = c(1, 2, 3), na.rm = TRUE)

# Comparison operators also need spaces
if (x > 0) cat('positive')
if (x >= 0 & y <= 100) cat('in range')

استخدم <- بدلًا من = للإسناد

# Correct: <- for assignment
name <- 'Alice'
score <- 95.5
results <- c(1, 2, 3)

# Correct: = inside function calls
round(3.14159, digits = 2)
read.csv('data.csv', header = TRUE, sep = ',')

# Avoid: = for top-level assignment
# name = 'Alice'   <- works but not idiomatic

cat('Assignment convention:', name, score)

حد الأسطر البالغ 80 محرفًا

# Bad: one very long line (hard to read)
result <- some_function(argument_one = 'value', argument_two = 100, argument_three = TRUE, argument_four = 'long_string')

# Good: break at commas, indent continuation
result <- some_function(
  argument_one   = 'value',
  argument_two   = 100,
  argument_three = TRUE,
  argument_four  = 'long_string'
)

cat('Readable at 80 chars')

عدم استخدام الفواصل المنقوطة

# Bad: semicolons and multiple statements per line
x <- 1; y <- 2; z <- x + y

# Good: one statement per line
x <- 1
y <- 2
z <- x + y

# The semicolon form is only acceptable in very short
# interactive throwaway code, never in scripts
cat('z =', z)

أسماء المتغيرات القابلة للقراءة

# Too cryptic:
d <- read.csv('data.csv')
tmp <- d[d$v1 > 0, ]
r <- lm(v2 ~ v1, data = tmp)

# Good names:
sales_data    <- read.csv('data.csv')
positive_rows <- sales_data[sales_data$revenue > 0, ]
revenue_model <- lm(profit ~ revenue, data = positive_rows)

# Avoid abbreviations that are not universally understood:
# n_obs is fine (number of observations)
# nrv is not (nobody knows what this is)

cat('Names tell the story')

الأقواس المعقوفة والمسافة البادئة

# Good style: brace on same line, 2-space indent
if (x > 0) {
  cat('positive\n')
} else {
  cat('non-positive\n')
}

# Good function definition:
calculate_bmi <- function(weight_kg, height_m) {
  bmi <- weight_kg / height_m^2
  round(bmi, 1)
}

cat('BMI:', calculate_bmi(70, 1.75))

المسافات داخل الأقواس وحول الفواصل

# Good: space after comma, not before
x <- c(1, 2, 3, 4, 5)
m <- matrix(1:9, nrow = 3, ncol = 3)

# Subsetting: no space before [ or inside []
first_row <- m[1, ]      # good
value     <- m[2, 3]    # good

# Bad:
# c(1,2,3)     <- no space after comma
# m[ 1, ]      <- space after [
# m[1 , ]      <- space before comma

cat('Spacing is consistent')

استخدام styler وlintr

# styler: reformat a file automatically
# install.packages('styler')
# styler::style_file('my_script.R')

# styler: reformat the whole project
# styler::style_dir('R/')

# lintr: check for style and potential bugs
# install.packages('lintr')
# lintr::lint('my_script.R')

# lintr reports issues like:
#   line 10: [object_name_linter] Variable 'myVar' should use snake_case
#   line 15: [spaces_around_ops_linter] No space before '<-'

cat('Style tools: styler + lintr')

تحقق سريع

الأسلوب وقابلية القراءة — أهم النقاط

# Putting it all together:

# Calculate summary statistics ----------------------------------------
calculate_summary <- function(values, remove_na = TRUE) {
  cleaned <- values[!is.na(values)]
  list(
    mean   = mean(cleaned),
    median = median(cleaned),
    sd     = sd(cleaned)
  )
}

test_scores <- c(85, 90, NA, 78, 92, 88)
stats <- calculate_summary(test_scores)
cat('Mean:', stats$mean, '\n')
cat('SD:  ', stats$sd)