Establish Commenting Guidelines

[yujeong-jeon]

Reference

This issue was raised based on this comment.

Background

As the project grows, maintaining clear and meaningful comments is becoming increasingly important. Currently, comments vary in style and detail, which can sometimes make it harder for contributors-especially external ones-to understand the reasoning behind certain implementations or deviations from lodash.

Motivation

• To improve code clarity and maintainability

• To help contributors understand the intent behind complex logic or design decisions

• To explicitly document any implicit improvements made for better performance compared to lodash, so contributors can easily identify and understand performance-related changes and optimizations

• To provide consistency across the codebase

Steps

1. Discuss and agree on a lightweight commenting guideline with maintainers and contributors

2. Review existing comments and update them according to the agreed guidelines

3. Add a dedicated section about commenting rules to the project’s CONTRIBUTING.md file, so that all current and future contributors have clear guidance on how to write and maintain comments consistently

cc. @NaverPayDev/frontend

[yujeong-jeon]

@yceffort-naver @2-one-week @AndrewSRP

I’d like to mention this specifically to those who have implemented functions so far:

Could you please add comments to your functions highlighting any performance improvements or areas where our code is better than lodash? Also, instead of referencing unpkg at the top, I suggest we briefly describe each function’s purpose based on the lodash documentation.

[yceffort-naver]

@yujeong-jeon I’m not exactly sure how to approach this—could you possibly share an example? 🤔

[yujeong-jeon]

@yceffort-naver Here’s an example based on the repeat function, showing how I’ve added comments to highlight the performance improvements compared to lodash:

https://github.com/NaverPayDev/hidash/pull/255/files

++ I forgot to add a role of the function.. I'll add it.

[yujeong-jeon]

Preparing for CONTRIBUTING.md

Commenting Guidelines

To ensure code readability and maintainability, please follow these guidelines when adding comments to the codebase:

1. Function Header Comments (Required)

• Description: Clearly and concisely describe the purpose and behavior of the function.
• Params: List and explain all parameters.
• Returns: Describe the return value(s).

Example:

/**
 * @description
 * Returns a new array with the results of calling a provided function on every element in the collection.
 * 
 * @param {Array|Object} collection - The collection to iterate over.
 * @param {Function} iteratee - The function invoked per iteration.
 * @returns {Array} The new mapped array.
 */

2. Internal Comments (Optional)

• Add internal comments only when necessary, such as for:
  • Explaining complex logic
  • Highlighting performance improvements
  • Noting non-obvious implementation details
• Keep these comments concise and focused.

3. Consistency with lodash

• Most function names are identical to lodash.
• However, @naverpay/hidash may introduce enhancements (e.g., improved type safety, interface changes).
• Please clearly document any differences or improvements from lodash in the relevant function’s header comment.

4. General Best Practices

• Keep comments up to date with code changes.
• Avoid redundant or obvious comments.
• Use English for all comments.

[yceffort]

This write-up is high-quality enough that we could totally put it in the README or the pull request description for everyone to see!

[yujeong-jeon]

@yujeong-jeon

• repeat
• isEqual
• isFunction
• findLastIndex
• findIndex
• isMap
• isSet
• toPairs
• entries
• values
• assign
• some
• filter
• pickBy
• zip
• unzip

@2-one-week

• map
• chunk

@AndrewSRP

• get
• find

@yceffort-naver

Everything else, aside from the functions mentioned above, ... (lord of hidash)

[yceffort-naver]

Everything else, aside from the functions mentioned above, ...