好文: API 設計與命名技巧

API 如何設計? 該怎麼命名? 一直都是很頭痛的問題~

API 的設計, 一個錯誤可能要40年才有機會修正, 詳細可見: 一個關於Ken Thompson的小故事.

此站還有蠻多 Tips 和教學文件可以參考.

API Design Tips

Naming is everything

The point is to reduce complexity

Eschew unnecessary side effects

Use Inversion of Control (IoC) to handle necessary side effects

Use events for the bulk of your IoC

Use Interfaces everywhere

Use Interfaces that cover everything you need, but not more and not less

Don't make your own gravity

return all of your results from the function call

The consumer isn't Sherlock Holmes

Distinguish types of failures

Support optional parameters

true and false are lousy arguments

Use consistent calling conventions

Nouns should be value types, verbs should be static functions. Or: Don't Make "Manager" Classes

Fail early

Don't be the weak link in the chain

One API at a time

One level of abstraction at a time

Expose wrappers for value types, but accept strings anyway

Always return the richest type

Implement IClonable, INotifyPropertyChanged, ISerializable and other handy interfaces for your value types

Provide flexibility and isolation for configuration

Keep your knickers to yourself

Only throw exceptions for the exceptional

Document the exceptions you throw

Document how to do what your consumers tend to do

Flag deviations from the norm

Consider shipping your unit tests

Don't ship an API you haven't used in a useful, working program

Naming Tips

下述轉載自: Naming Tips

Methods, Classes and Variables

Do not name methods "ProcessData()"

Use naming to help you design the program

If it's general, it better be generalized

Avoid discussing hard work

Avoid class names that end with "Manager"

Use singular names for enumerations

Hungarian notation should encode meaning, not type

Don't hide behind your names

Don't forget to have a vowel movement

Consistency, Consistency, Consistency

Don't be afraid to rename

Frameworks & Libraries

Prefer namespaces instead of "nsStupidClassPrefix"

Extend a generic namespace, don't create MyCompanyName.Widgets

Databases

Use pluralized names for tables

Use aux_ and meta_ for tables that contain derived data or housekeeping junk

Name surrogate primary keys after the table

Use a postfix to show the kind of key

Things

Name physical things what they are, not what they're doing

Name logical things after what they're doing, not what they are

Avoid the "Category" problem