Skip to content

Latest commit

 

History

History
278 lines (216 loc) · 8.64 KB

GUIDELINES.md

File metadata and controls

278 lines (216 loc) · 8.64 KB
Raw

Compose SDK Guidelines

Table of Contents

Motivation

We follow official Guidelines For Compose when developing our Compose SDK. On top of that, to make the code consistent and easy to maintain, we developed a set of coding conventions described in this document.

Contributions to this project are very much welcome! Even if some of the requirements below are not met, don't hesitate to submit your code changes. 💙

Project Structure

Since the SDK is quite small, we decided to package the code by layer. The main packages are listed below:

stream-chat-android-compose
├── ...
├── viewmodel
├── state
├── ui
│   └── components
├── previewdata
  • viewmodel: Contains ViewModels for bound UI components.
  • state: Contains classes encapsulating state for Composable UI components.
  • ui: Contains screen, bound and stateless UI components.
  • ui/components: Contains reusable independent components that can be used as building blocks when creating fully custom UI.
  • previewdata: Contains sample data for component previews.

For simplicity, we try to have only one public Composable UI component per file. Also, within each layer we try to package the code by feature. The following is an example of how to package a feature:

stream-chat-android-compose
├── ...
├── viewmodel
│      └── messages          // ViewModels and factories for the "messages" feature
├── state
│      └── messages          // Models and entities for the "messages" feature
├── ui
│      └── messages          // Higher-level components for the "messages" feature 
│      └── components
│             └── messages   // Utility components for the "messages" feature

Writing documentation

KDoc Comments

For code comments, we use KDoc. We believe that all of the code should be covered with KDoc. This includes classes, methods, fields, parameters and return values.

When writing code comments, keep the following in mind:

  • Use full sentences: start with capital letters, end with punctuation. 
    - the default message container for all messages
+ The default message container for all messages.
  • Do NOT put dashes between the KDoc tag and its contents, as these get interpreted as bullet points (KDoc supports markdown). 
    - * @param modifier - Modifier for styling.
+ * @param modifier Modifier for styling.
- * @return - The display name for the given channel.
+ * @return The display name for the given channel.
  • Do NOT end comments with * */. Just use */. 
    - * */
+ */
  • Use square brackets to refer to other declarations (classes, functions, properties, etc) in the code where applicable. 
    Checks if the [Channel] is distinct.

Naming Conventions

Naming Components

When choosing a name for your component, try to avoid the naming conventions from Android view-based system.

Do

@Composable
fun LoadingIndicator() {
    // ...
}

Don't

@Composable
fun LoadingView() {
    // ...
}

Naming Listeners

We prefer using present tense for action handlers.

Do

@Composable
fun MyComposable(onChannelClick: () -> Unit) {
    // ...
}

Don't

@Composable
fun MyComposable(onChannelClicked: () -> Unit) {
    // ...
}

Naming State

When choosing a name for a class encapsulating state for a Composable component, simply append the State suffix to the Composable name.

data class MessageItemState(
    // ...  
)

@Composable
fun MessageItem(messageItemState: MessageItemState) {
    // ...
}

Naming Resources

Resource names must start with stream_compose_ prefix.

Customizing Components

Customization Options

Customization options should be exposed where possible:

  • Modifiers for styling
  • Action handlers
  • Styling options
  • Slot APIs

Example:

@Composable
fun UserAvatar(
    // State
    user: User,
    // Modifier and Styling
    modifier: Modifier = Modifier,
    shape: Shape = ChatTheme.shapes.avatar,
    // Action Handlers
    onClick: (() -> Unit)? = { },
    // Slot APIs
    onlineIndicator: @Composable BoxScope.() -> Unit = { ... }
)

Slot APIs

We heavily rely on Slot APIs when building our components. When designing a complex component, it is hard to expose every possible customization parameter. In that case, consider exposing customization slots instead.

Rules when implementing Slot APIs:

  • Consistent naming: When exposing content slots consider using these common names: leadingContent, centerContent, trailingContent, footerContent, headerContent, itemContent, content.
  • Default implementation: The default implementation of a content slot should be internal, located in the same source file and should be named according to this pattern: Default*LeadingContent, Default*CenterContent, etc.
  • Inner padding: A component containing slots should be as simple as possible. That's why we try to handle paddings inside slots (for example, instead of adding a margin between slots).

Example:

@Composable
fun MyComposable(
    myComposableState: MyComposableState,
    // ... Modifier, Styling and Actions
    leadingContent: @Composable RowScope.(MyComposableState) -> Unit = {
        DefaultMyComposableLeadingContent(it)
    },
    headerContent: @Composable ColumnScope.(MyComposableState) -> Unit = {
        DefaultMyComposableHeaderContent(it)
    },
    centerContent: @Composable ColumnScope.(MyComposableState) -> Unit = {
        DefaultMyComposableCenterContent(it)
    },
    footerContent: @Composable ColumnScope.(MyComposableState) -> Unit = {
        DefaultMyComposableFooterContent(it)
    },
    trailingContent: @Composable RowScope.(MyComposableState) -> Unit = {
        DefaultMMyComposableTrailingContent(it)
    },
) {
    Row {
        leadingContent(messageItem)

        Column {
            headerContent(messageItem)

            centerContent(messageItem)

            footerContent(messageItem)
        }

        trailingContent(messageItem) 
    }
}

@Composable
internal fun RowScope.DefaultMyComposableLeadingContent(myComposableState: MyComposableState) {
    // The padding is handled inside the default implementation
    val modifier = Modifier.padding(start = 16.dp)
    // ...
}

Drawable colors

Whenever possible, prefer to create drawable resources that have a #000000 color, and then tint them at the use site (instead of creating drawable resources that are specific colors, e.g. red or grey).

Example:

Icon(
    painter = painterResource(id = R.drawable.stream_compose_ic_share),
    contentDescription = null,
    tint = ChatTheme.colors.textHighEmphasis
)

Component Previews

We provide component previews for stateless components.

When creating component previews, keep the following in mind:

  • Place previews in the same source file as the Composable.
  • Set a display name for the preview.
  • Store sample data for the preview in the previewdata package.

Example:

@Composable
fun MyComposable() {
    // ...
}

@Preview(name = "MyComposable Preview")
@Composable
fun MyComposablePreview() {
    ChatTheme {
        MyComposable()
    }
}